Spring boot集成swagger构建接口管理文档
一，swagger简介
swagger是一个工具，用于自动生成web网站对外提供的服务接口文档，并且以web页面的形式进行展示。
优势：可以自动生成API文档 ，能降低前后端的沟通成本。
二，项目的基本结构
三，idea项目构建思路
3.1pom依赖
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.yfy</groupId>
<artifactId>bootsw</artifactId>
<version>0.0.1-SNAPSHOT</version>
<packaging>jar</packaging>
<name>bootsw</name>
<description>Demo project for Spring Boot</description>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.0.5.RELEASE</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
<java.version>1.8</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<!--swagge依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
<!--lombok插件依赖-->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.16.10</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
3.2application.properties配置
3.3实体类
package com.yfy.bootsw.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel(value = "用户模型")
public class UserEntity {
@ApiModelProperty(value="id" ,required= true,example = "123")
private Integer id;
@ApiModelProperty(value="用户姓名" ,required=true,example = "yyyy")
private String name;
public Integer getId() {
return id;
}
public void setId(Integer id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
@Override
public String toString() {
return "DemoDoctor [id=" + id + ", name=" + name + "]";
}
}
3.4Controller类
package com.yfy.bootsw;
import com.yfy.bootsw.entity.UserEntity;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;
@Api(value = "会员接口")
@RestController
public class AnimalController {
@ApiOperation(value = "接口测试demo", nickname = "swagger接口测试demo昵称")
@GetMapping("/getDemo")
public String getDemo(){
return "调用方法成功。。。。。";
}
@ApiOperation(value = "获取会员信息接口", nickname = "根据userName获取用户相关信息")
@ApiImplicitParam(name = "userName", value = "用户名称", required = true, dataType = "String")
@PostMapping("/postMember")
public String postMember(@RequestParam String userName) {
return userName;
}
@ApiOperation(value = "添加用户信息", nickname = "nickname是什么", notes = "notes是什么", produces = "application/json")
@PostMapping("/postUser")
@ResponseBody
@ApiImplicitParam(paramType = "query", name = "userId", value = "用户id", required = true, dataType = "int")
public UserEntity postUser(@RequestBody UserEntity user, @RequestParam("userId") int userId) {
if (user.getId() == userId) {
return user;
}
return new UserEntity();
}
@ApiOperation(value = "添加用户信息", nickname = "添加用户接口", notes = "测试添加用户的接口", produces = "application/json")
@PostMapping("/addUser")
@ResponseBody
@ApiImplicitParams({@ApiImplicitParam(paramType = "query", name = "userName", value = "用户姓名", required = true, dataType = "String"), @ApiImplicitParam(paramType = "query", name = "id", value = "用户id", required = true, dataType = "int") })
public UserEntity addUser(String userName, int id) {
UserEntity userEntity = new UserEntity();
userEntity.setName(userName);
userEntity.setId(id);
return userEntity;
}
}
3.5config类的编写
package com.yfy.bootsw.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration //spring boot配置注解
@EnableSwagger2 //启用swagger2功能注解
public class Swagger2Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
// api扫包范围
.apis(RequestHandlerSelectors.basePackage("com.yfy.bootsw")).paths(PathSelectors.any()).build();
}
/**
* 创建该API的基本信息（这些基本信息会展现在文档页面中）
* 访问地址：http://项目实际地址/swagger-ui.html
*
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("Swagger接口发布测试").description("测试|Swagger接口功能")
//服务条
.termsOfServiceUrl("www.baidu.com")
.contact(new Contact("yangjie", "https://blog.csdn.net/OnlyOneFrist", ""))
.version("1.0")
.build();
}
}