Swagger--一种强大的Api文档自动化工具

为什么要用swagger？它解决了什么问题？

随着spring boot、spring cloud等微服务的流行，在微服务的设计下，小公司的微服务小的几十，大公司大的拥有几百上万的微服务。这么多微服务必定产生了大量的接口调用，而接口的调用就必定要写接口文档。

在微服务的盛行下，成千上万的接口文档编写，不可能靠人力来编写，故swagger就产生了，它采用了自动化实现并解决了人力编写接口文档的问题，他通过在接口及实体类上添加几个注解的方式就能在项目启动后自动化生产接口文档。

Swagger提供了一个全新的维护Api文档的方式，并且有着4大优点：

1. 自动化生产文档，只需要少量的注解，Swagger就可以根据代码自动生成API文档，很好的保证了文档的时效性。
2. 跨语言性，支持40多种语言。
3. Swagger UI呈现出来的是一份可交互的API文档，我们可以直接在文档页面尝试API的调用，省去了准备复杂的调用参数的过程。
4. 还可以将文档规范导入相关工具，这些工具会为我们自动地创建自动化测试。

那么接下来就让我们来尝试接入Swagger吧

步骤一：pom导入依赖

<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>

步骤二：添加配置文件

spring.swagger2.enabled=true   #是否开启

步骤三：编写Swagger配置类

package com.jaryn.boot.swagger.config;

import org.springframework.beans.factory.annotation.Value;
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.service.Documentation;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Value("${spring.swagger2.enabled}")
    private Boolean swaggerEnable;

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(swaggerEnable)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.jaryn.boot.swagger")) //注意这里要更换为根目录包名，代表需要生成接口文档的目录包
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("接口文档")
                .description("Spring Boot联系")
                .termsOfServiceUrl("")
                .version("1.0")
                .build();
    }
}

 

这样我们就算接入完成了，可以通过http://127.0.0.1:8080/swagger-ui.html来测试是否正常

如果发现这个页面打不开并且提示No handler found for GET /swagger-ui.html,那可能是因为资源映射问题导致的

我们在访问http://127.0.0.1:8188/swagger-ui.html 时，这个swagger-ui.html相关的所有前端静态文件都在springfox-swagger-ui-2.8.jar里面。目录如下：

Spring Boot自动配置本身不会自动把/swagger-ui.html这个路径映射到对应的目录META-INF/resources/下面。我们加上这个映射即可。代码如下

@Configuration
public class WebMvcConfig extends WebMvcConfigurerAdapter {
     @Override
     void addResourceHandlers(ResourceHandlerRegistry registry) {
         registry.addResourceHandler("swagger-ui.html")
                 .addResourceLocations("classpath:/META-INF/resources/")
 
         registry.addResourceHandler("/webjars/**")
                 .addResourceLocations("classpath:/META-INF/resources/webjars/")
     }
}

添加好后，重启，成功！

整合完成后我们来说是用法：

常用注解：

- @Api()用于类； 
表示标识这个类是swagger的资源 
- @ApiOperation()用于方法； 
表示一个http请求的操作 
- @ApiParam()用于方法，参数，字段说明； 
表示对参数的添加元数据（说明或是否必填等） 
- @ApiModel()用于类 
表示对类进行说明，用于参数用实体类接收 
- @ApiModelProperty()用于方法，字段 
表示对model属性的说明或者数据操作更改 
- @ApiIgnore()用于类，方法，方法参数 
表示这个方法或者类被忽略 
- @ApiImplicitParam() 用于方法 
表示单独的请求参数 
- @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

具体使用举例说明： 

@Api() 
用于类；表示标识这个类是swagger的资源 
tags–表示说明 
value–也是说明，可以使用tags替代 
但是tags如果有多个值，会生成多个list

@Api(value="用户controller",tags={"用户操作接口"})
@RestController
public class UserController {

}

@ApiOperation() 用于方法；表示一个http请求的操作 
value用于方法描述 
notes用于提示内容 
tags可以重新分组（视情况而用） 
@ApiParam() 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等） 
name–参数名 
value–参数说明 
required–是否必填

@Api(value="用户controller",tags={"用户操作接口"})
@RestController
public class UserController {
     @ApiOperation(value="获取用户信息",tags={"获取用户信息copy"},notes="注意问题点")
     @GetMapping("/getUserInfo")
     public User getUserInfo(@ApiParam(name="id",value="用户id",required=true) Long id,@ApiParam(name="username",value="用户名") String username) {
     // userService可忽略，是业务逻辑
      User user = userService.getUserInfo();
      return user;
  }

@ApiModel()用于类 ；表示对类进行说明，用于参数用实体类接收 
value–表示对象名 
description–描述 
都可省略 
@ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改 
value–字段说明 
name–重写属性名字 
dataType–重写属性类型 
required–是否必填 
example–举例说明 
hidden–隐藏

@ApiModel(value="user对象",description="用户对象user")
public class User implements Serializable{
    private static final long serialVersionUID = 1L;
     @ApiModelProperty(value="用户名",name="username",example="xingguo")
     private String username;
     @ApiModelProperty(value="状态",name="state",required=true)
      private Integer state;
 
      @ApiModelProperty(value="id数组",hidden=true)
      private String[] ids;
      private List<String> idList;
     //省略get/set
}

@ApiIgnore()用于类或者方法上，可以不被swagger显示在页面上 
比较简单, 这里不做举例

@ApiImplicitParam() 用于方法 
表示单独的请求参数 
@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam 
name–参数ming 
value–参数说明 
dataType–数据类型 
paramType–参数类型 
example–举例说明

  @ApiOperation("查询测试")
  @GetMapping("select")
  //@ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query")
  @ApiImplicitParams({
  @ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"),
  @ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")})
  public void select(){
}

好了，swagger的常用注解就说完了。我是觉得挺好用的而且在对面大量的api接口时候真的省事不少，而且调试也方便，今天就做个记录方便自己以后回看。