Spring Boot集成Swagger2 生成API文档

最新推荐文章于 2022-03-10 14:08:01 发布

原创最新推荐文章于 2022-03-10 14:08:01 发布 · 83 阅读

0 ·

CC 4.0 BY-SA版权

本文为博主原创文章，未经博主允许不得转载。

开始

新建springboot工程,springboot 版本为 2.1.3 ,Swagger2 版本为2.9.2

添加依赖

<dependencies>
       
       <!--Swagger相关-->
       <dependency>
           <groupId>io.springfox</groupId>
           <artifactId>springfox-swagger2</artifactId>
           <version>2.9.2</version>
       </dependency>
       <dependency>
           <groupId>io.springfox</groupId>
           <artifactId>springfox-swagger-ui</artifactId>
           <version>2.9.2</version>
       </dependency>
         <!--Swagger相关-->
   
   </dependencies>

swagger 配置

@EnableSwagger2
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .pathMapping("/")
                .select() // 选择那些路径和api会生成document
                       // 对所有api进行监控
                .apis(RequestHandlerSelectors.any())
                //不显示错误的接口地址 //错误路径不监控
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                       // 对根下所有路径进行监控
                .paths(PathSelectors.regex("/.*"))
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("接口文档")
                .contact(new Contact("Felix", "", "xxx@qq.com"))
                .description("SWAGGER_2生成的接口文档")
                .termsOfServiceUrl("NO terms of service")
                .license("The Apache License, Version 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .version("v1.0")
                .build();
    }
}

相关注解

@Api 主要用在类上

1 2	@Api(value = "用户接口",description = "用户相关api") public class UserController {}

@ApiOperation 主要用在方法上其中value简短的叙述，notes一般是该方法的详细描述

1	@ApiOperation(value = "登录",notes = "登录接口")

@ApiImplicitParam 注解用于前端传入的参数
当有多个参数时，需要用@ApiImplicitParams将@ApiImplicitParam包起来
使用ApiImplicitParam时，需要指定paramType,这样也便于swagger ui 生成参数的输入格式
paramType： path, query, body, header, form
dataType: 默认String
defaultValue：参数的默认值

1 2	@ApiImplicitParams({@ApiImplicitParam(name = "username", value = "用户名"), @ApiImplicitParam(name = "password", value = "密码")})

@ApiParam

@ApiModel

@ApiModel(value = "User", description = "用户对象")
public class User {

}

@ApiModelProperty

1 2	@ApiModelProperty(value = "ID") private Integer id;

@ApiResponses、@ApiResponse：方法返回值的说明

@ApiResponses({
	@ApiResponse(code = 400, message = "请求参数没填好"),
	@ApiResponse(code = 404, message = "请求路径不对")
})

参考swagger官方注解文档：http://docs.swagger.io/swagger-core/apidocs/index.html

参考

官方文档
 swagger2