【框架】Swagger

Swagger2 2.9.2 in 2019

https://swagger.io/
Swagger on Spring Boot

Swagger 是一个规范和完整的框架（文档管理工具）；
Slogan: The World’s Most Popular API Tooling
Swagger是一个开发API的工具，亦是此领域全世界最大的框架，遵循了OpenAPI的规范，可以让开发者跨越整个API的生命周期，从设计到文档到测试到发布；

• 提问：Swagger对后端人员来说有什么好处？
  不再需要像以前一样关注页面数据的渲染，页面跳转逻辑的处理，只需要关注业务逻辑，简单提供接口；
  前端通过接口获取数据，渲染页面；

• 提问：接口应该以什么样的形式呈现给前端？
  可以通过前后两端的口头约定；或者后端先编写接口，再编写接口文档；
  但是这两种形式都会浪费开发时间；
  建议使用Swagger开发接口，后端开发好了接口的同时，就自动生成了接口文档；
  这样就节省了前后端沟通成本，减少了后端的接口文档编写成本；

DESIGN:
一个可视化编辑器，编辑接口文档，可设计新的API或编辑已存在的API，有实时响应；

BUILD:
根据接口文档生成语言代码，把接口文档的定义转换成代码，可生成服务端、客户端的依赖，支持40种语言；

DOCUMENT:
Swagger UI 用来展示文档；

另外，还可以把已有文档生成代码，

---

接口文档：
除了Word文档，我们也需要用到接口文档；
Word是生硬的文字，然而为了满足需求的大量变更，或者填补新系统的缺陷（新系统可能不好管理文档，文档会散落到到处都是），我们需要接口文档；
需要使用接口文档的情况：

• 前后端分离：前端得到接口文档，前后端就可以通过接口文档来交互；因为前端可能无需关心后端如何实现，所以一个好的文档管理十分必要；
• 第三方合作：若我们和另一方同时开发一个新项目，肯定要先定义接口文档，
• 自己测试时：有个好的接口文档也很方便，接口文档可以代替POSTMAN来直接测试项目；

---

配置

————————————————————————————

POM

springfox-swagger2 和 springfox-swagger-ui
jackson-core是测试数据以JSON格式返回的依赖包（可选）；

<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>
<dependency>
        <groupId>org.codehaus.jackson</groupId>
        <artifactId>jackson-core-asl</artifactId>
        <version>1.9.13</version>
</dependency>

————————————————————————————

初始化 SwaggerConfig

Config下新建SwaggerConfig：

必须有两个注解：@Configuration @EnableSwagger2

@Configuration
@EnableSwagger2
public class SwaggerConfig {
}

这样就可以在浏览器访问文档了：
访问：http://localhost:8080/swagger-ui.html

——————————————
SwaggerConfig 模版：
（一个@Bean Docket方法是一个group；什么是group？页面搜索：.groupName）

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                // .groupName("default group")  当前group名字
                // .apiInfo(apiInfo())
                // .ignoredParameterTypes()  过滤指定类型的参数（可选）一定写在select()之前
                // .enable()  此文档可被访问的场合（可选）一定写在select()之前
                .select()   // select和apis/paths和build 三者的顺序一定不能错
                .apis(RequestHandlerSelectors.？？(""))  // 接口方法的展示
                .paths(PathSelectors.？？？())   // 接口方法的展示（apis和paths选一即可）
                .build()   // 一定要写在最后
                ;
    }

——————————————
若浏览器访问Swagger文档弹出对话框报错：

Unable to infer base url. 
This is common when using dynamic servlet registration or when the API is behind an API Gateway. 
The base url is the root of where all the swagger resources are served. 
For e.g. if the api is available at http://example.org/api/v2/api-docs 
then the base url is http://example.org/api/. Please enter the location manually: 

是因为SwaggerConfig没有被@Component到；
建议在启动类上加上注解：（选择Swagg