Swagger-CSDN博客

本文链接：https://blog.csdn.net/qq_45853799/article/details/120252785

Swagger

1. Swagger-UI基本介绍

Swagger-UI是HTML, Javascript, CSS的一个集合，可以动态地根据注解生成在线API文档。
官网：https://swagger.io/tools/swagger-ui/
相关资料：狂神说集成Swagger

2. 常用注解

@Api：用于修饰Controller类，生成Controller相关文档信息
@ApiModel：用于修饰Model类
@ApiOperation：用于修饰Controller类中的方法，生成接口方法相关文档信息
@ApiParam：用于修饰接口中的参数，生成接口参数相关文档信息
@ApiModelProperty：用于修饰实体类的属性，当实体类是请求参数或返回结果时，直接生成相关文档信息

3. 使用方式

添加项目依赖

Springfox3.0版本：使用{host}/swagger-ui/访问文档，并且不再需要@EnableSwagger2注解

<!--Swagger-UI API文档生产工具-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

Springfox2.x版本：使用{host}/swagger-ui.html or {host}/swagger-ui访问文档

<!--Swagger-UI API文档生产工具-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.4</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.4</version>
</dependency>

参考文档：https://github.com/LalithK90/Swagger3-Documentation-Springboot-Sample

添加Swagger-UI配置

Swagger对生成API文档的范围有三种不同的选择
- 生成指定包下面的类的API文档
- 生成有指定注解的类的API文档
- 生成有指定注解的方法的API文档

SwaggerConfig配置文件：

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //配置是否启用Swagger，如果是false，在浏览器将无法访问，动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示
                .enable(true) 
                // 配置分组名称
                .groupName("Test")
                // 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                .select()
                //为当前包下controller生成API文档
                .apis(RequestHandlerSelectors.basePackage("com.study.mall.controller"))
                /*
                为有@Api注解的Controller生成API文档
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                为有@ApiOperation注解的方法生成API文档
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                */
                //配置如何通过path过滤
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("SiKun", "http://www.sikun.site","psikun@foxmail.com");
        return new ApiInfoBuilder()
                .title("坤坤小淘气")
                .description("mall项目学习")
                .contact(contact)
                .version("1.0")
                .build();
    }
}

配置详解：

.enable(true)：配置是否启用Swagger，如果是false，在浏览器将无法访问，动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示

.groupName("Test")：配置分组的名称，如果要配置多个分组，可以返回多个Docket

@Bean
public Docket docket1(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}

.select()：通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口

.apis()：配置扫描接口

//为指定包下controller生成API文档
.apis(RequestHandlerSelectors.basePackage("com.study.mall.controller"))
//为有@Api注解的Controller生成API文档
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
//为有@ApiOperation注解的方法生成API文档
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))

.paths(PathSelectors.any())：配置如何通过path过滤

any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制

.build()：执行构建

ApiInfo类：一些基本的信息，显示到首页
- .contact(Contact contact)：需要传递一个Contact对象，查看源码发现，构造函数需要name，url，email三个参数