Swagger 常用主题、注解及具体实例（超全）

╰+哭是因爲堅強的太久メ 2022-11-08 14:24 238阅读 0赞

# 主题 #

### 1.默认主题 ###

1）依赖

<dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger-ui</artifactId>
       <version>2.9.2</version>
    </dependency>

2）**URL**：ip:port/swagger-ui.html

3）页面展示

1.  首页

![在这里插入图片描述][20210129232341255.png]

1.  接口

![在这里插入图片描述][20210129232349282.png]

1.  测试

![在这里插入图片描述][20210129232405201.png]

### 2.BootStrap-UI（推荐） ###

1）依赖

<dependency>
       <groupId>com.github.xiaoymin</groupId>
       <artifactId>swagger-bootstrap-ui</artifactId>
       <version>1.9.1</version>
    </dependency>

2）**URL**：ip:port/doc.html

3）页面

1.  首页

![在这里插入图片描述][20210129232425535.png]

1.  接口

![在这里插入图片描述][20210129232433443.png]

1.  测试

![在这里插入图片描述][20210129232442578.png]

### 3.Layui-UI ###

1）依赖

<dependency>
       <groupId>com.github.caspar-chen</groupId>
       <artifactId>swagger-ui-layer</artifactId>
       <version>1.1.3</version>
    </dependency>

2）**URL**：ip:port/docs.html

3）页面

1.  首页

![在这里插入图片描述][20210129232450952.png]

1.  接口

![在这里插入图片描述][2021012923245912.png]

1.  测试

![在这里插入图片描述][20210129232506207.png]

### 4.MG-UI ###

1）依赖

<dependency>
       <groupId>com.zyplayer</groupId>
       <artifactId>swagger-mg-ui</artifactId>
       <version>1.0.6</version>
    </dependency>

2）**URL**：ip:port/document.html

3）页面

1.  首页

![在这里插入图片描述][20210129232514238.png]

1.  接口

![在这里插入图片描述][20210129232521429.png]

1.  测试

![在这里插入图片描述][2021012923252949.png]

# 注解 #

![在这里插入图片描述][20210129220710897.png]

但是，这也看不明白啊。。。接口连个中文说明都没有。。。所以，Swagger 提供了很多注解，就是让我们去为每个类、每个接口/参数、每个Model 写解释说明的。

## 1.用于类的注解 ##

### @Api：资源描述 ###

标识这个类是 Swagger 的资源，

@Api(tags = "商户相关接口")
    @RestController
    @RequestMapping("/merchants")
    public class MerchantsController

可以设置的属性如下：

![在这里插入图片描述][2021012922113013.png]

*  values：字符串；说明该类的作用，在类旁边的小字显示
 *  **tags**：字符串；标签（也可理解成分类），会替换 Controller 名称；当多个 Controller 的 tags 相同时，它们的方法会在一起显示
    
    ![在这里插入图片描述][20210129221144467.png_pic_center]
 *  consumes：字符串；指定处理请求的提交内容类型(Content-Type)，例如 application/json
 *  produces：字符串；指定返回的内容类型，即仅当请求头的 Accept 类型中包含该指定类型才返回，例如:application/json
 *  protocols：字符串；标识当前的请求支持的协议，例如：http`、`https、ws
 *  hidden：true/false；隐藏整个 Controller，作用与 @ApiIgnore 相似，但没有 @ApiIgnore 功能强大

### @ApiIgnore：资源过滤 ###

有些时候我们并不是希望所有的 Rest API 都呈现在文档上，这种情况下 Swagger2 提供给我们了两种方式配置，一种是基于 @ApiIgnore 注解另一种是在 Docket 上增加筛选。两种方式的区别是，Docket 配置的规则，可以对多个接口器过滤作用，而 @ApiIgnore 只能作用于单个接口。

> 关于 Docket 上增加筛选请看[上一篇][Link 1]…

![在这里插入图片描述][20210129221209997.png_pic_center]

如果想在文档中屏蔽掉删除用户的接口（user/delete），那么只需要在删除用户的方法上加上 @ApiIgnore 即可。

## 2.用于方法的注解 ##

### @ApiOperation：方法描述 ###

@ApiOperation(value = "创建商户", notes = "开发中")
    public Response createMerchants

可以设置的属性如下：

![在这里插入图片描述][20210129221221465.png]

*  **value**：字符串；方法摘要，在路径旁显示
 *  **note**：字符串；方法详细描述  
    ![在这里插入图片描述][20210129230141804.png_pic_center]
 *  tags：字符串数组；对方法进行分类，一个方法可以有多个分类
    
    ![在这里插入图片描述][20210129221244328.png]
 *  response：Class；设置当前请求的返回值类型，String.class；会覆盖自动识别的返回类型，一般用不上
 *  responseContainer：字符串；说明包装的容器，默认情况下，有效值为 List、Set、Map；在定义通用 Response 后，一般用不上
 *  httpMethod：字符串；指定请求方式，比如 GET、POST、PUT
 *  consumes：字符串；指定处理请求的提交内容类型(Content-Type)，例如 application/json
 *  produces：字符串；指定返回的内容类型，即仅当请求头的 Accept 类型中包含该指定类型才返回，例如:application/json

### @ApiImplicitParam(s)：参数描述 ###

参数描述，可用在方法头。

ApiImplicitParams 只有一个属性 `ApiImplicitParam[] value();`是 ApiImplicitParam 的数组，比如

@ApiImplicitParams({ 
            @ApiImplicitParam(name = "id", value = "商户ID")
    })
    @GetMapping("/{id}")
    public Response getMerchantsInfo(@PathVariable Integer id) { 
        return null;
    }

所以，来看看 @ApiImplicitParam 有哪些属性：

![在这里插入图片描述][20210129221313845.png_pic_center]

*  **name**：字符串；参数名
 *  **value**：字符串；参数的汉字说明、解释
 *  defaultValue：字符串；参数的默认值
 *  allowableValues：字符串；限制此参数接收的值，可使用的值或值得范围
    
     *  `(`表示是大于，`)`表示是小于
     *  `[`表示是大于等于，`]`表示是小于等于
     *  `infinity`表示无限大，`-infinity`表示负无限大
 *  allowEmptyValue：true/false；允许参数为空，默认为 false
 *  **required**：true/false；参数是否必须传
 *  **paramType**：字符串；参数放在哪个地方（可以自动识别）
 *  header --> 参数在request headers 里边提交：@RequestHeader
    
     *  path（用于restful接口）–> 参数以地址的形式提交：@PathVariable
     *  query --> 直接跟参数完成自动映射赋值：@RequestParam
     *  form --> 以form表单的形式提交，仅支持POST：@RequestParam
     *  body --> 以流的形式提交，仅支持POST：@RequestBody
 *  **dataType**：字符串；参数类型，参数的数据类型（默认String），可以使用类名或原始数据类型（使用不当汇报类型转换异常）
 *  dataTypeClass：Class；参数的类，如果提供则覆盖 dataType
 *  example：字符串；非请求体（body）参数的**单个请求**示例
 *  examples：Example；参数的举例说明，仅适用于 body 类型。

### @ApiParam：参数描述 ###

参数描述，用在每个参数前面，比如

@PostMapping("/create")
    // 注：这里如果使用 @ApiImplicitParam 会出现无法识别的问题
    public Response createMerchants(
            @ApiParam(name = "request", value = "创建商户请求对象") @RequestBody CreateMerchantsRequest request)

@ApiParam 的可以设置的属性如下：

![在这里插入图片描述][20210129221441693.png_pic_center]

*  **name**：字符串；参数名
 *  **value**：字符串；参数的汉字说明、解释
 *  defaultValue：字符串；参数默认值
 *  allowableValues：字符串；限制此参数接收的值，可使用的值或值得范围
    
     *  `(`表示是大于，`)`表示是小于
     *  `[`表示是大于等于，`]`表示是小于等于
     *  `infinity`表示无限大，`-infinity`表示负无限大
 *  allowEmptyValue：true/false；允许参数为空，默认为 false
 *  **required**：true/false；参数是否必须传
 *  example：字符串；非请求体（body）参数的**单个请求**示例
 *  examples：Example；参数的举例说明，仅适用于 body 类型。

> 关于 @ApiImplicitParam 和 @ApiParm 它俩都能为方法的请求参数做注释，区别有：
> 
> 1.  @ApiImplicitParam 可以在方法前使用，而 @ApiParm 只能在参数前使用
> 2.  @ApiImplicitParam 提供的可设置属性更多，特别是 **paramType** 很关键
> 3.  对于 @RequestBody 标识的 Json 字符串，不能使用 @ApiImplicitParam，会出现无法识别的情况
>     
>     1.  方案一：通过 @ApiParm 对 @RequestBody 的参数进行说明
>     2.  方案二：直接不对该参数使用注解，将注释的任务交给实体类（@ApiModel）
> 
> 另外，两者是可以混搭使用的，一般推荐使用 @ApiImplicitParam(s)，但是注意 @RequestBody 的情况。

### @ApiResponse(s) ###

跟上面 @ApiImplicitParam(s) 一样，@ApiResponses 也是只有唯一个属性`ApiResponse[] value();`

@ApiResponses({ 
            @ApiResponse(code = 1, message = "非HTTP状态码，Response code字段值，描述：成功，返回该商户ID"),
            @ApiResponse(code = 0, message = "非HTTP状态码，Response code字段值，描述：失败")
    })
    @PostMapping("/create")
    public Response createMerchants

下面来看看 @ApiResponse 有哪些属性

![在这里插入图片描述][20210129221458937.png_pic_center]

*  **code**：整形数；相应的状态码
 *  **message**：字符串；相应消息，例如"电话号码已存在"
 *  **response**：Class；消息有效负载的可选响应类，对应于响应消息对象的 schema 字段；对于使用通用 Response 的情况，该字段很关键
 *  responseHeaders：ResponseHeader\[\]；可能响应的 header 列表
 *  responseContainer：String；声明响应的容器，有效值为List,Set,Map，任何其他值都将被忽略

## 3.用于实体类的注解 ##

### @ApiModel：实体类描述 ###

用于请求类或者响应类上，表示一个返回响应数据的信息

@ApiModel("创建商户的请求对象")
    @Data
    @AllArgsConstructor
    @NoArgsConstructor
    public class CreateMerchantsRequest

@ApiModel 可以设置的属性有：

![在这里插入图片描述][20210129221522847.png_pic_center]

*  **value**：字符串；实体类的备用名，如果不设置，则会采用原类名
 *  description：字符串；实体类的说明
 *  parent：Class；父类的一些信息

### @ApiModelProperty：实体类成员描述 ###

@ApiModel("创建商户的请求对象")
    @Data
    @AllArgsConstructor
    @NoArgsConstructor
    public class CreateMerchantsRequest { 
    
        @ApiModelProperty("商户名")
        private String name;
    
        @ApiModelProperty("商户logo的URL")
        private String logoUrl;
    
        @ApiModelProperty("营业执照URL")
        private String businessLicenseUrl;
    
        @ApiModelProperty("联系电话")
        private String phone;
    
        @ApiModelProperty("地址")
        private String address;
    }

ApiModelProperty 可以设置的属性有：

![在这里插入图片描述][20210129221532910.png_pic_center]

*  **value**：字符串；字段说明
 *  name：字符串；重写字段名称
 *  dataType：字符串；重写字段类型
 *  required：true/false；是否必填
 *  allowableValues：字符串；限制此参数接收的值，可使用的值或值得范围
    
     *  `(`表示是大于，`)`表示是小于
     *  `[`表示是大于等于，`]`表示是小于等于
     *  `infinity`表示无限大，`-infinity`表示负无限大
 *  allowEmptyValue：true/false；允许参数为空，默认为 false
 *  example：String；示例
 *  hidden：true/false；是否在文档中隐藏该字段

## 完整代码 ##

> 注：下面的示例代码取自我曾经写过的一个项目，只截取了部分 Swagger 相关代码。

@Api(tags = "商户相关接口")
    @Slf4j
    @RestController
    @RequestMapping("/merchants")
    public class MerchantsController { 
    
    
        @ApiOperation(value = "创建商户", notes = "开发中")
        @ApiResponses({ 
                @ApiResponse(code = 1, message = "非HTTP状态码，Response code字段值，描述：成功，返回该商户ID"),
                @ApiResponse(code = 0, message = "非HTTP状态码，Response code字段值，描述：失败")
        })
        @PostMapping("/create")
        public Response createMerchants(
                @ApiParam(name = "request", value = "创建商户请求对象", required = true) @RequestBody CreateMerchantsRequest request) { 
            return null;
        }
    
    
        @ApiOperation("获取商户信息")
        @ApiImplicitParams({ 
                @ApiImplicitParam(name = "id", value = "商户ID")
        })
        @ApiResponses({ 
                @ApiResponse(code = 1, message = "非HTTP状态码，Response code字段值，描述：成功", response = Merchants.class),
                @ApiResponse(code = 0, message = "非HTTP状态码，Response code字段值，描述：失败")
        })
        @GetMapping("/{id}")
        public Response getMerchantsInfo(@PathVariable Integer id) { 
            return null;
        }
    }

![在这里插入图片描述][20210129222046198.png]

[20210129232341255.png]: /images/20221023/b4ee03c3dd7d47e49630a8f9497d3669.png?
[20210129232349282.png]: /images/20221023/92ecc5b11432454695fd4aa33ece3890.png?
[20210129232405201.png]: /images/20221023/5e9e24f8ad674ae7b59e21213355ce62.png?
[20210129232425535.png]: /images/20221023/295e7e137ef14f0da49e741782568865.png?
[20210129232433443.png]: /images/20221023/28f023bc7d634391ade4dd3f5d84b8a7.png?
[20210129232442578.png]: /images/20221023/f9ecb3d121c643e8b175076469bd2c9f.png?
[20210129232450952.png]: /images/20221023/bab6fe36d760497f825f4dff1c2c0cc0.png?
[2021012923245912.png]: /images/20221023/f874b973687544ac90d319bc5148b21c.png?
[20210129232506207.png]: /images/20221023/7d9b59e756514f939d3feecad42e309b.png?
[20210129232514238.png]: /images/20221023/f9aba904748b4a4f9576d5314cebefee.png?
[20210129232521429.png]: /images/20221023/63aef4de91e84814adf2ce7e94acf4f4.png?
[2021012923252949.png]: /images/20221023/2e50b3fd5af4473ba66fa9f9a9af2061.png?
[20210129220710897.png]: /images/20221023/3c2e381acf854159bde9d57ab56dcde3.png?
[2021012922113013.png]: /images/20221023/53b9ec61fb7046019a4dc0f777b98e02.png?
[20210129221144467.png_pic_center]: /images/20221023/c9af2b8fc9b746caa0ef49d535782717.png
[Link 1]: https://blog.csdn.net/weixin_43935927/article/details/113395427
[20210129221209997.png_pic_center]: /images/20221023/01f3b41b873b403eab36370ba1a35acb.png
[20210129221221465.png]: /images/20221023/df112d8da4e8414f8cc4963b936201be.png?
[20210129230141804.png_pic_center]: /images/20221023/4b7c72286b4e4730bd3d7bea51a36016.png
[20210129221244328.png]: /images/20221023/81e9274e974e4868a703a6f1933c84c9.png?
[20210129221313845.png_pic_center]: /images/20221023/f709e06df4c248cba125808306ec6621.png
[20210129221441693.png_pic_center]: /images/20221023/12d1fb4930404bd6918b7973b31e7048.png
[20210129221458937.png_pic_center]: /images/20221023/2a9a359420834f69bf882eb6c8100301.png
[20210129221522847.png_pic_center]: /images/20221023/e001bc1d5a0c4a1785303376f49af12b.png
[20210129221532910.png_pic_center]: /images/20221023/6551b1cce3e64c5f9d557788ad822bb5.png
[20210129222046198.png]: /images/20221023/fc5571bb072540cab93784e6e3f0b7ba.png?