SpringBoot2.x集成Swagger2

什么是swagger，为什么要使用swagger?

当下大部分新项目开发时都会采用前后端分离的模式，API接口就成了前后端唯一的关联、约定。前端工程师如何知道哪个接口是干嘛的？里面需要什么参数？请求的方式是什么？… 这时候就需要一份简洁且详尽API文档，swagger就是用来自动生成API文档的，用于定义API文档的一个框架。

如何使用swagger?

环境说明：

IDEA版本： 2019版

JDK：1.8

maven.version：3.6.0

spring-boot.version：2.1.7.RELEASE

swagger2.version：2.9.2

Swagger优缺点：
优点：

• 易用性好，支持多种注解，自动生成接口文档界面，Swagger UI提供很好的API接口的UI界面，可以很方面的进行API接口的调用。 (不同的版本ui界面有所差别，ui风格个人不是很喜欢，个人目前在使用SpringBoot2.x集成knife4j
  )
• 时效性和可维护性好，API文档随着代码变更而变更。 Swagger是根据注解来生成文API档的，我们可以在变更代码的时候顺便更改相应的注解即可。
• 易于测试，可以将文档规范导入相关的工具（例如 SoapUI）, 这些工具将会为我们自动地创建自动化测试。
• 集成简单，通过添加pom依赖和简单注解配置，内嵌于应用中就可同时发布API接口文档界面，无需部署独立服务。

缺点：

• 重复利用性差，因为Swagger是网页打开，在进行接口测试的时候很多参数无法进行保存，因此不易于重复利用。
• 复杂的场景不易模拟，比如使用token鉴权的，可能每次都需要先模拟登录，再来进行接口调用。需配合postman等工具使用；

1.导入pom依赖

### 2.swagger配置类

@Configuration
@EnableSwagger2
@ConditionalOnExpression("${swagger.enable}") //开启访问接口文档的权限
@Profile({"dev", "test"})// 设置 dev test 环境开启
public class SwaggerConfig extends WebMvcConfigurationSupport {
    //过滤Swagger响应的API
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //swagger要扫描的包
                .apis(RequestHandlerSelectors.basePackage("com.mamba.platform.cli.auth.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("项目API接口")
                .description("用户登陆接口")
                .termsOfServiceUrl("localhost:8801/auth")
                .contact(new Contact("项目API接口","localhost:8801/auth/swagger-ui.html","xxxx@qq.com"))
                .version("1.0")
                .build();
    }

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
                // 解决静态资源无法访问（可选）
        registry.addResourceHandler("/**")
                .addResourceLocations("classpath:/static/");
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

}

.yml配置

spring:
  profiles:
    active: dev
swagger:
  enable: true

3. 在controller、method、bean上加上注释

这里边涉及到多个API，我来向小伙伴们分别说明：

@Api注解可以用来标记当前Controller的功能。
@ApiOperation注解用来标记一个方法的作用。
@ApiImplicitParam注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入。
如果有多个参数，则需要使用多个@ApiImplicitParam注解来描述，多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中。
需要注意的是，@ApiImplicitParam注解中虽然可以指定参数是必填的，但是却不能代替@RequestParam(required = true)，前者的必填只是在Swagger2框架内必填，抛弃了Swagger2，这个限制就没用了，所以假如开发者需要指定一个参数必填，@RequestParam(required = true)注解还是不能省略。
@ApiModel加在对象上
@ApiModelProperty加在属性上
@ApiIgnore() /添加这个注解将不会显示在UI界面上
…
具体可以参考 swagger官方注解文档

4. 访问根目录/swagger-ui.html

http://ip:port/auth/swagger-ui.html
注意：
.yml配置中如果添加了如下

server:
  port: 8801
  servlet:
    context-path: /auth

需访问：http://localhost:8801/auth/swagger-ui.html

欢迎Star and Fork 源码

SpringBoot2.x集成Knife4j