1. 关于Swagger

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

相信采用 Spring Boot 开发的小伙伴几乎是用来构建 RESTful API ，而文档自然是不可缺少的一部分，Swagger 的出现，既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。

另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。

作用总结：

• 接口文档在线生成
• 方便功能测试

集成后的效果图如下：

2. 开始集成

2.1 添加依赖

在 pom.xml 中添加 swagger 依赖

      
     
           
      
       io.springfox
           
      
       springfox-swagger-ui
           
      
       2.7.0
       
      
     
           
      
       io.springfox
           
      
       springfox-swagger2
           
      
       2.7.0
       
     

2.2 配置Swagger

applicaton.yml

# Swagger界面内容配置 swagger:   title: TMax API接口文档   description: TMax Api Documentation   version: 1.0.0   termsOfServiceUrl: https://www.sscai.club   contact:     name: niceyoo     url: https://www.sscai.club     email: apkdream@163.com

如上配置请置于根节点，如下图所示：

Swagger2Config.java

新建一个 Swagger2Config.java 的配置类：

1. 添加 @Configuration 注解，用于定义配置类，方便被Spring Boot配置；
2. 添加 @EnableSwagger2 注解启动 Swagger 文档构建能力。

完整代码如下：

@Slf4j @Configuration @EnableSwagger2 public class Swagger2Config {
        @Value("${swagger.title}")     private String title;     @Value("${swagger.description}")     private String description;     @Value("${swagger.version}")     private String version;     @Value("${swagger.termsOfServiceUrl}")     private String termsOfServiceUrl;     @Value("${swagger.contact.name}")     private String name;     @Value("${swagger.contact.url}")     private String url;     @Value("${swagger.contact.email}")     private String email;     private List
     
       securitySchemes() {
            List
      
        apiKeys = new ArrayList<>();         apiKeys.add(new ApiKey("Authorization", "accessToken", "header"));         return apiKeys;     }     private List
       
         securityContexts() {
            List
        
          securityContexts = new ArrayList<>();         securityContexts.add(SecurityContext.builder()                 .securityReferences(defaultAuth())                 .forPaths(PathSelectors.regex("^(?!auth).*$")).build());         return securityContexts;     }     private List
         
           defaultAuth() {
            AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");         AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];         authorizationScopes[0] = authorizationScope;         List
          
            securityReferences = new ArrayList<>();         securityReferences.add(new SecurityReference("Authorization", authorizationScopes));         return securityReferences;     }     @Bean     public Docket createRestApi() {         log.info("加载Swagger2");         return new Docket(DocumentationType.SWAGGER_2)             .apiInfo(apiInfo()).select()             ## 扫描所有有注解的api，用这种方式更灵活             .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))             .paths(PathSelectors.any())             .build()             .securitySchemes(securitySchemes())             .securityContexts(securityContexts());     }     private ApiInfo apiInfo() {         return new ApiInfoBuilder()                 .title(title)                 .description(description)                 .termsOfServiceUrl(termsOfServiceUrl)                 .contact(new Contact(name, url, email))                 .version(version)                 .build();     } }
          
         
        
       
      
     

方法讲解：

通过 createRestfulApiDocs() 方法创建 Docket 的 Bean 之后，apiInfo() 用来创建该 API 的基本信息。（这些基本信息会展现在文档页面中，如最开始的预览图，增加一些文档自定义信息）

select() 函数返回一个 ApiSelectorBuilder 实例用来控制哪些接口暴露给Swagger 来展现，本例采用扫描所有带有 API 注解的对外开放，同时，你也可以采用指定扫描的包路径来定义，Swagger 则会扫描该包下所有 Controller定义的 API，并产生文档内容（除了被@ApiIgnore指定的请求）。

如果采用扫描指定包路径的话，需要修改 createRestApi() 方法的 apis 部分：

.apis(RequestHandlerSelectors.basePackage("com.lemon.security.web.controller"))

2.3 新建entity和controller测试

entity：VideoCategory.java

@Data @Entity @Table(name = "v_category") @TableName("v_category") @ApiModel(value = "视频类型") public class VideoCategory extends TmaxBaseEntity {
        private static final long serialVersionUID = 1L;     @ApiModelProperty(value = "类型名称")     private String title;     @ApiModelProperty(value = "排序值")     @Column(precision = 10, scale = 2)     private BigDecimal sortOrder;     @ApiModelProperty(value = "是否启用 0启用 -1禁用")     private Integer status = CommonConstant.STATUS_NORMAL; }

controller：VideoCategoryController 主要以添加、查询为例

@Slf4j @RestController @Api(description = "视频类型管理接口") @RequestMapping("/tmax/videoCategory") @Transactional public class VideoCategoryController extends TmaxBaseController
     
       {
        @Autowired     private VideoCategoryService videoCategoryService;     @Override     public VideoCategoryService getService() {
            return videoCategoryService;     }     @RequestMapping(value = "/add", method = RequestMethod.POST)     @ApiOperation(value = "添加")     public Result
      
     

常用注解说明：

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

项目启动后访问：http://localhost:端口号(例如8080)/swagger-ui.html

我们尝试操作一下 add() 方法：

1. 填写实体基本信息
2. 点击 Try it out! 按钮

3. 最后

在上边的整个过程中，我们了解 Swagger 除了查看接口功能外，还提供了调试测试功能，点击“Try it out！”按钮，即可完成了一次请求调用！

此时，你也可以通过几个 POST 请求来验证之前的 POST 请求是否正确。相比为这些接口编写文档的工作，我们增加的配置内容是非常少而且精简的，对于原有代码的侵入也在忍受范围之内。

因此，在构建 RESTful API 的同时，加入 Swagger 来对 API 文档进行管理，是个不错的选择。