Springboot集成swagger自动生成Api文档

本篇主要是配置swagger，若需要使用generator自动生成swagger相关注解，可参考 generator代码自动生成工具（动态生成注释、类注解、方法注解等）适用于swagger等需要配置实体类的场景

1 pom导包

<!-- swagger -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.swagger/swagger-annotations -->
<dependency>
   <groupId>io.swagger</groupId>
   <artifactId>swagger-annotations</artifactId>
   <version>1.5.22</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.swagger/swagger-models -->
<dependency>
   <groupId>io.swagger</groupId>
   <artifactId>swagger-models</artifactId>
   <version>1.5.22</version>
</dependency>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>
<dependency>
   <groupId>org.codehaus.jackson</groupId>
   <artifactId>jackson-core-asl</artifactId>
   <version>1.9.13</version>
</dependency>

2 swagger配置类

注意配置swagger的basePackage

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * swagger工具
 * @author dulinxiao
 * @create 2021-03-22 1:43 PM
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("API接口文档")
                .description("XX平台")
                .version("1.0.0")
                .build();
    }
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

3 swagger使用

3.1 使用在实体类

@ApiModel 说明该类是一个model实体类
@ApiModelProperty 指定属性名及备注

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.io.Serializable;

/**
 * @author linxiao
 */
@ApiModel
public class SysUser implements Serializable {
    @ApiModelProperty(value = "主键", name = "id")
    private String id;
    @ApiModelProperty(value = "登录账号", name = "userName")
    private String userName;
    @ApiModelProperty(value = "用户名", name = "trueName")
    private String trueName;
   
    public String getId() {
        return id;
    }    
    public void setId(String id) {
        this.id = id;
    }
    public String getUserName() {
        return userName;
    }
    public void setUserName(String userName) {
        this.userName = userName;
    }
    public String getTrueName() {
        return trueName;
    }
    public void setTrueName(String trueName) {
        this.trueName = trueName;
    }
}

3.2 使用在接口

@Api 该类是一个api，生成api文档
@ApiOperation 该方法是一个接口，指定该接口功能
@ApiImplicitParam 指定接口入参

/**
 * @author dulinxiao
 * @create 2021-03-22 1:52 PM
 */
@RestController
@RequestMapping("/user")
@Api(value = "用户信息管理",description = "用户信息管理")
public class UserController {

    @Resource
    private UserService userService;

    @RequestMapping(method = RequestMethod.GET , value = "/userById")
    //方法说明
    @ApiOperation(value = "获取用户",notes = "根据id获取用户")
    //方法入参
    @ApiImplicitParam(paramType = "query", name = "id", dataType = "int", required = true, value = "用户id")
    public Object getUserById(int id){
        return null;
    }
}

4 swagger访问

启动项目后访问 http://127.0.0.1:8080/swagger-ui.html

完结撒花🎉🎉🎉