SpringFox 学习

叁歲伎倆 2022-05-23 01:08 137阅读 0赞

[官网][Link 1]、[源代码][Link 2]

参考  
[Springfox与swagger的整合使用][Springfox_swagger]

## 前言 ##

Swagger

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

swagger-springmvc 发展出 SpringFox

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

## 使用 ##

Spring Boot 和 Swagger UI 集成  
Spring Boot 集成springfox后，默认就带了swagger-ui.html了，不需要此操作。如果想对界面进行定制，则需要先从 github swagger-ui 上下载Swagger-UI, 把该项目dist目录下的内容拷贝到项目的resources的目录public下，然后再修改（具体百度）。

### 注解 ###

参考  
[swagger注解 详细说明][swagger_]

#### @Api ####

用在类上，说明该类的作用

@Api(value = "UserController", description = "用户相关api")

### @ApiOperation ###

用在方法上，说明方法的作用

@ApiOperation(value = "查找用户", notes = "查找用户", httpMethod = "GET", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)

### @ApiImplicitParams ###

用在方法上包含一组参数说明

### @ApiImplicitParam ###

用在@ApiImplicitParams注解中，指定一个请求参数的各个方面  
paramType：参数放在哪个地方

header–>请求参数的获取：@RequestHeader
    query–>请求参数的获取：@RequestParam
    path（用于restful接口）–>请求参数的获取：@PathVariable
    body（不常用）
    form（不常用）

name：参数名  
dataType：参数类型  
required：参数是否必须传  
value：参数的意思  
defaultValue：参数的默认值

@ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "唯一id", required = true, dataType = "Long", paramType = "path"),
    })

### @ApiResponses ###

用于表示一组响应

### @ApiResponse ###

用在@ApiResponses中，一般用于表达一个错误的响应信息  
code：数字，例如400  
message：信息，例如”请求参数没填好”  
response：抛出异常的类

@ApiResponses(value = {
            @ApiResponse(code = 400, message = "No Name Provided") })

### @ApiModel ###

Swagger-core builds the model definitions based on the references to them throughout the API introspection.  
The @ApiModel allows you to manipulate the meta data of a model from a simple description or name change to a definition of polymorphism.  
描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）

@ApiModel(value = "用户实体类")

### @ApiModelProperty ###

描述一个model的属性

@ApiModelProperty(value = "登录用户")
    @ApiIgnore //使用这个注解忽略这个接口

[Link 1]: http://springfox.github.io/springfox/
[Link 2]: https://github.com/springfox/springfox
[Springfox_swagger]: https://www.cnblogs.com/getupmorning/p/7267076.html
[swagger_]: https://www.2cto.com/kf/201709/680224.html