Swagger使用文档

Swagger简介

由于前后端分离，前端或者后端无法做到及时协商，最终导致问题爆发，所以程序猿写代码时都是很暴躁的。

这个时候，就可以用到Swagger了，它号称世界上最流行的API框架，Restful Api文档在线自动生成器。还可以在线测试API接口，不必特意去下载Postman，ApiPost去测试接口。还支持多种语言,如：Java，PHP(PHP是世界上最好的语言！)等

贴个官网：https://swagger.io/

Springboot集成Swagger

集成Swagger需要引入pom依赖，下面是代码

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>

添加后编写HelloController，再新建一个Config文件夹，在里面新建一个SwaggerConfig配置java文件，确保运行成功。(下面是SwaggerConfig的代码)

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {  
}

访问：http://localhost:8080/swagger-ui.html ，就可以可以看到swagger的界面了。

如果运行报错404，你需要在Config文件夹里新建一个java文件指向jar包里的静态资源。

@Configuration
// @EnableWebMvc
public class CorsConfig extends WebMvcConfigurationSupport {


    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/**")
                .addResourceLocations("classpath:/resource/")
                .addResourceLocations("classpath:/static/")
                .addResourceLocations("classpath:/public");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }


    @Override
    public void addCorsMappings(CorsRegistry registry) {
        // 设置允许跨域的路径
        registry.addMapping("/**")
                // 设置允许跨域请求的域名
                .allowedOrigins("*")
                // 是否允许证书 不再默认开启
                .allowCredentials(true)
                // 设置允许的方法
                .allowedMethods("*")
                // 跨域允许时间
                .maxAge(3600);
    }
}

配置Swagger

1、Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger。

写在SwaggerConfig里

@Bean //配置docket以配置Swagger具体参数
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2);
}

2、还可以通过apiInfo()属性配置文档信息

//配置文档信息
private ApiInfo apiInfo() {
   Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
   return new ApiInfo(
           "Swagger学习", // 标题
           "学习演示如何配置Swagger", // 描述
           "v1.0", // 版本
           "http://terms.service.url/组织链接", // 组织链接
           contact, // 联系人信息
           "Apach 2.0 许可", // 许可
           "许可链接", // 许可连接
           new ArrayList<>()// 扩展
  );
}

3.配置了的话需要Docket关联上apiInfo()

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}

配置扫描接口

1、构建Docket时通过select()方法配置扫描接口。

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.example.application.controller"))
      .build();
}

2、重启项目测试，由于我们配置根据包的路径扫描接口，所以我们只能看到一个Controller类。

3、除了通过包路径配置扫描接口外，还可以通过配置其他方式扫描接口，这里注释一下所有的配置方式：

any() // 扫描所有，项目中的所有接口都会被扫描到
none() // 不扫描接口
// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
basePackage(final String basePackage) // 根据包路径扫描接口

4、除此之外，还可以配置接口扫描过滤：

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.example.application.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/post开头的接口
      .paths(PathSelectors.ant("/post/**"))
      .build();
}

5、这里的可选值还有:

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

Api接口配置

Swagger可以自动生成接口文档，他是怎样生成的呢？你之需要根据Swagger的规范添加注释就可以了。

常用注解：

Swagger注解	简单说明
@Api(tags = "xxx模块说明")	作用在模块类上
@ApiOperation("xxx接口说明")	作用在接口方法上
@ApiModel("xxxPOJO说明")	作用在模型类上：如VO、BO
@ApiModelProperty(value = "xxx属性说明",hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam("xxx参数说明")	作用在参数、方法和字段上，类似@ApiModelProperty

示例：

@ApiOperation("格微的接口")
@PostMapping("/gewei")
@ResponseBody
public String gewei(@ApiParam("这个名字会被返回")String username){
   return username;
}

 才疏学浅，如果有不对的地方请指正。感谢B站遇见狂神说。