SpringCloud之Springfox和Swagger

---

前言

诞生背景：前后端分离 >> 业务和工作效率的需求
前后端分离之后，人员之间的关系就是API，在没有比这种方式更简洁干脆地了（目前为止）
对于程序员，能够用程序来解决的问题都不是问题（谁没事去写接口文档啊，有时间不如多去看看代码）

效果展示

---

Swagger是什么？

SwaggerUI就是一个的可视化API文档

---

官方:swagger是一个流行的API开发框架，这个框架以“开放API声明”（OpenAPI Specification，OAS）为基础，对整个API的开发周期都提供了相应的解决方案，是一个非常庞大的项目（包括设计、编码和测试，几乎支持所有语言）。
OAS本身是一个API规范，它用于描述一整套API接口，包括一个接口是GET还是POST请求啊，有哪些参数哪些header啊，都会被包括在这个文件中。它在设计的时候通常是YAML格式，这种格式书写起来比较方便，而在网络中传输时又会以json形式居多，因为json的通用性比较强。

Springfox是什么？

Springfox是一个整理API的框架

---

官方：Springfox是一个开源的API Doc的框架， 它的前身是swagger-springmvc，可以将我们的Controller中的方法以文档的形式展现。
由于Spring的流行，Marty Pitt编写了一个基于Spring的组件swagger-springmvc，用于将swagger集成到springmvc中来。而springfox则是从这个组件发展而来，同时springfox也是一个新的项目，本文仍然是使用其中的一个组件springfox-swagger2。
pringfox-swagger2依然是依赖OSA规范文档，也就是一个描述API的json文件，而这个组件的功能就是帮助我们自动生成这个json文件，我们会用到的另外一个组件springfox-swagger-ui就是将这个json文件解析出来，用一种更友好的方式呈现出来。

运行机制

原理：需要什么就拿什么

既然前言部分说了这两个就是一个API的文档，就是这两个工具吧API的生成、显示、编辑都包圆了。
这时候我们考虑的就是对接口文档根据自己的需求进行格式化，然后才是使用。

配置文件

@Configuration //必须存在
@EnableSwagger2 //必须存在
@EnableWebMvc //必须存在
@ComponentScan(basePackages = {"com.xiaoming.SpringMVC.controller"}) //必须存在 扫描的API Controller package name 也可以直接扫描class (basePackageClasses)
public class SwaggerConfig{
    @Bean
    public Docket customDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("小花", "http://www.cnblogs.com/", "[email protected]");
        return new ApiInfoBuilder()
                .title("前台API接口")
                .description("前台API接口")
                .contact(contact)
                .version("1.1.0")
                .build();
    }
}

底层实现：

springfox为我们提供了一个Docket（摘要）类，我们需要把它做成一个Bean注入到spring中，显然，我们需要一个配置文件，并通过一种方式（显然它会是一个注解）告诉程序，这是一个Swagger配置文件。

一个OSA规范文档需要许多信息来描述这个API，springfox允许我们将信息组合成一个ApiInfo的类，作为构造参数传给Docket。

常用注解

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

---

学以致用

依赖

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

@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值
@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类
@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性

restful

1、REST 是面向资源的，这个概念非常重要，而资源是通过 URI 进行暴露。
比如：左边是错误的设计，而右边是正确的

GET /rest/api/getDogs --> GET /rest/api/dogs 获取所有小狗狗 
GET /rest/api/addDogs --> POST /rest/api/dogs 添加一个小狗狗 
GET /rest/api/editDogs/:dog_id --> PUT /rest/api/dogs/:dog_id 修改一个小狗狗 
GET /rest/api/deleteDogs/:dog_id --> DELETE /rest/api/dogs/:dog_id 删除一个小狗狗 

2、REST很好地利用了HTTP本身就有的一些特征，如HTTP动词、HTTP状态码、HTTP报头等等。
HTTP动词

GET     获取一个资源 
POST    添加一个资源 
PUT     修改一个资源 
DELETE  删除一个资源 
HTTP状态码
200 OK 
400 Bad Request 
500 Internal Server Error
HTTP报头
Authorization 认证报头 
Cache-Control 缓存报头 
Cnotent-Type  消息体类型报头 

怎么用RESTful
1、每个资源使用2个URL，网址中只能有名词

2、对于资源的操作类型由HTTP动词来表示

3、统一的返回结果

4、返回正确的状态码

5、允许通过HTTP内容协商，建议格式预定义为JSON

6、对可选发杂的参数，使用查询字符串（？）

7、返回有用的错误信息(message)

8、非资源请求用动词，这看起似乎和1中的说法有矛盾，但这里指的是非资源，而不是资源

---

参考文章：

https://www.cnblogs.com/free-wings/p/9841781.html
https://www.cnblogs.com/water-1/p/10820235.html