Swagger2基本使用

废话篇

前言

接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后接口文档又变成重中之重。接口文档固然重要，但是由于项目周期等原因后端人员经常出现无法及时更新导致前端人员抱怨接口文档和实际情况不一致。

很多人员会抱怨别人写的接口文档不规范，不及时更新。但是当自己写的时候确实最烦去写接口文档。这种痛苦只有亲身经历才会牢记于心。

如果接口文档可以实时动态生成就不会出现上面问题Swagger可以完美的解决上面的问题。
即，使得前后端分离开发更方便

什么是openAPI

Open API规范(OpenAPI Specification)以前叫做 Swagger规范 是REST API的API描述格式
REST API 即同一个url根据不同的请求方式实现不同的功能

• Open API文件允许描述整个 API，
• 包括 每个访问地址的类型。POST或 GET
• 每个操作的参数包括输入输出参数
• 认证方法。
• 连接信息，声明，使用团队和其他信息 Open API规范可以使用YAML 或JSON 格式进行编写。这样更利于我们和机器进行阅读。

Swagger简介

Swagger是一套围绕 Open API规范构建的开源工具，可以帮助设计，构建，记录和使用REST API。
Swagger 工具包括的组件：

Swagger Editor :基于浏览器编辑器，可以在里面编写 Open API规范。类似Markdown 具有实时预览描述文件的功能
Swagger UI: 将 Open API规范呈现为交互式 API 文档。用可视化 UI 展示描述文件Swagger Codegen :将
OpenAPI规范生成为服务器存根和客户端库。通过 SwaggerCodegen 可以将描述文件生成 html 格式和
cwiki形式的接口文档，同时也可以生成多种言语的客户端和服务端代码。 SwaggerInspector:和Swagger
UI有点类似，但是可以返回更多信息，也会保存请求的实际参数数据。 Swagger
Hub:集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到 Swagger Hub 中。

在 Swagger Hub 中可以完成上面项目的所有工作需要注册账号，分免费版和收费版使用Swagger，就是把相关的信息存储在它定义的描述文件里面(yml或json 格式)再通过维护这个描述文件可以去更新接口文档，以及生成各端代码

Springfox

使用Swagger时如果碰见版本更新或迭代时，只需要更改 Swagger的描述文件即可。但是在频繁的更新项目版本时很多开发人员认为即使修改描述文件(yml或json)也是一定的工作负担，久而久之就直接修改代码，而不去修改描述文件了，这样基于描述文件生成接口文档也失去了意义
Marty Pitt 编写了一个基 Spring的组件 swaggerSpring-fox就是根springmv据这个组件发展而来的全新项目。
Spring-fox是根据代码生成接口文档，所以正常的进行更新项目版本，修改代码即可而不需要跟随修改描述文件
Spring-fox利用自身 AOP 特性，把 Swagger 集成进来，底层还是Swagger。但是使用起来确方便很多
所以在实际开发中，都是直接使用spring-fox

使用篇

swagger的基本使用

1、引入依赖

3.0版本需要添加springboot-starter

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
</dependency>

3.0以下的

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

2、配置config

3.0.0之前版本需使用@EnableSwagger2注解
3.0.0版本则不需要@EnableSwagger2注解，取而代之是@EnableOpenApi

3、启动项目，访问swagger-ui界面url地址

3.0.0之前的版本访问是： /swagger-ui.html
3.0.0版本访问是： /swagger-ui/index.html

4、配置相关信息

在swaggerConfig中bean类中配置相关的swagger信息

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(
                new ApiInfo("TITLE",
                        "description",
                        "version",
                        "",
                        new Contact("lio","https://blog.csdn.net/weixin_58286934?type=blog","510629467@qq.com"),
                        "li",
                        "http://www.baidu.com",
                        new ArrayList<VendorExtension>()))
                //是否启动swagger
                .enable(true)
                //RequestHandlerSelectors，配置要扫描接口的方式
                // basePackage: 配置要扫描的包
                // any(): 扫描全部
                // none():不扫
                // withclassAnnotation: 扫描类上的注解
                //withMethodAnnotation:扫描方法上的注解
                .select().apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
                //过滤 any全部拒绝 none全部放行
                .paths(PathSelectors.ant("/swag/*"))
                .build();
    }