三十一章：Swagger集成

1.用途

1.接口的文档在线自动生成
2.功能测试

描述（规范和避免测试时接口不清楚）：
  Swagger™的目标是为REST APIs 定义一个标准的，
  与语言无关的接口，使人和计算机在看不到源码或者
  看不到文档或者不能通过网络流量检测的情况下能
  发现和理解各种服务的功能。当服务通过Swagger定义，
  消费者就能与远程的服务互动通过少量的实现逻辑。
  类似于低级编程接口，Swagger去掉了调用服务时的很多猜测。

 

 

2.关于Swagger的项目

1.Swagger Codegen: 
  通过Codegen可以将描述文件生成html格式和cwiki形式的接口文档，
  同时也能生成多钟语言的服务端和客户端的代码。
  支持通过jar包，docker，node等方式在本地化执行生成。
  也可以在后面的Swagger Editor中在线生成。

  一个模板驱动引擎，通过分析用户Swagger
  资源声明以各种语言生成客户端代码

2.Swagger UI:
   提供了一个可视化的UI页面展示描述文件。
   接口的调用方、测试、项目经理等都可以在
   该页面中对相关接口进行查阅和做一些简单的接口请求。
   该项目支持在线导入描述文件和本地部署UI项目。

3.Swagger Editor: 
  类似于markendown编辑器的编辑Swagger描述文件的编辑器，
  该编辑支持实时预览描述文件的更新效果。
  也提供了在线编辑器和本地部署编辑器两种方式。

4.Swagger Inspector: 
   感觉和postman差不多，是一个可以对接口进行测试的在线版的postman。
   比在Swagger UI里面做接口请求，会返回更多的信息，
   也会保存你请求的实际请求参数等数据。

5.Swagger Hub：
  集成了上面所有项目的各个功能，
  你可以以项目和版本为单位，
  将你的描述文件上传到Swagger Hub中。
  在Swagger Hub中可以完成上面项目的所有工作，
  需要注册账号，分免费版和收费版。

6.Springfox Swagger: 
  Spring 基于swagger规范，
  可以将基于SpringMVC和Spring Boot项目的项目代码，
  自动生成JSON格式的描述文件。
  本身不是属于Swagger官网提供的。

7.Swagger-tools:
  提供各种与Swagger进行集成和交互的工具。
  例如模式检验、Swagger 1.2文档
  转换成Swagger 2.0文档等功能

8.Swagger-core: 
  用于Java/Scala的的Swagger实现。
  与JAX-RS(Jersey、Resteasy、CXF...)、
  Servlets和Play框架进行集成。

9.Swagger-js: 
  用于JavaScript的Swagger实现。

10.Swagger-node-express: 
   Swagger模块，用于node.js的Express web应用框架。

 

 3.在springBoot项目中使用Swagger

第一步：导入依赖（maven）

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger2</artifactId>

    <version>2.2.2</version>

</dependency>

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger-ui</artifactId>

    <version>2.2.2</version>

</dependency>

第二步：配置类(注：这是和application.java同等级的)

             告诉系统我需要swagger，且声明swagger设置

package com.swaggerTest;
 
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
/**
 * Swagger2配置类
 * 在与spring boot集成时，放在与Application.java同级的目录下。
 * 通过@Configuration注解，让Spring来加载该类配置。
 * 再通过@EnableSwagger2注解来启用Swagger2。
 */
@Configuration
@EnableSwagger2
public class Swagger2 {
    
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     * 
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swaggerTest.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    
    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("更多请关注http://www.baidu.com")
                .termsOfServiceUrl("http://www.baidu.com")
                .contact("sunf")
                .version("1.0")
                .build();
    }

总结:

   1.采用扫码的方式，说明那些接口可以去访问，如下：

apis(RequestHandlerSelectors.basePackage("com.swaggerTest.controller"))

2.通过createRestApi函数创建Docket的Bean之后，
  apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）


第三步：注解需要扫描的接口，方便理解接口的功能（注意注解的问题），如下：

@Api：
  用在类上，表示标识这个类是swagger的资源

  参数说明：
    tags–表示说明 
    value–也是说明，可以使用tags替代 
    但是tags如果有多个值，会生成多个list

@ApiOperation：
  用于方法上，表示一个http请求的操作 
  参数：
   value用于方法描述 
   notes用于提示内容 
   tags可以重新分组（视情况而用） 

@ApiImplicitParams : 
   用在方法上包含一组参数说明。

   参数：
     paramType：指定参数放在哪个地方：
       header：请求参数放置于Request Header，使用@RequestHeader获取
 query：请求参数放置于请求地址，使用@RequestParam获取
       path：（用于restful接口）-->请求参数的获取：@PathVariable
       body：（不常用）
       form（不常用）

name–参数名
     value–参数说明 
     dataType–数据类型 
     paramType–参数类型 
     example–举例说明

@ApiImplicitParam：
  用于方法 表示单独的请求参数

@ApiResponses：用于表示一组响应

@ApiResponse：
   用在@ApiResponses中，
   一般用于表达一个错误的响应信息

   code：数字，例如400

   message：信息，例如"请求参数没填好"

   response：抛出异常的类   

@ApiModel：
     描述一个Model的信息
    （一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
     @ApiModel()用于类 
     表示对类进行说明，用于参数用实体类接收 

    参数：
      value–表示对象名 
      description–描述 
    

 @ApiModelProperty：
    用于方法，字段 
    表示对model属性的说明或者数据操作更改 

    参数：

       value–字段说明 

       name–重写属性名字 

       dataType–重写属性类型 

       required–是否必填 

       example–举例说明 

       hidden–隐藏

@ApiParam()
   用于方法，参数，字段说明； 
   表示对参数的添加元数据（说明或是否必填等） 

   参数：
     name–参数名 
     value–参数说明 
     required–是否必填

@ApiIgnore()
  用于类，方法，方法参数 
  表示这个方法或者类被忽略

 

第四步：访问Swagger ui

   启动项目，根据依赖的配置，可以访问Swagger ui

  例如：http://localhost:8080/swagger-ui.html

注意事项：
   1.注意@ApiImplicitParam的使用会影响程序运行，
     如果使用不当可能造成控制器收不到消息

参数paramType会直接影响程序的运行期，

如果paramType与方法参数获取使用的注解不一致，

会直接影响到参数的接收。

  2.Conntroller中定义的方法必须在@RequestMapper中
    显示的指定RequestMethod类型，否则SawggerUi会
    默认为全类型皆可访问， API列表中会生成多条项目。