在 上一篇 我们详细的介绍了使用 Swagger 时需要做的配置，现在已经能得到一个我们自己想要的页面了

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

1.用于类的注解

@Api：资源描述

@Api(tags = "商户相关接口")
@RestController
@RequestMapping("/merchants")
public class MerchantsController 
可以设置的属性如下：
 
 
values：字符串；说明该类的作用，在类旁边的小字显示
 
 
tags：字符串；标签（也可理解成分类），会替换 Controller 名称；当多个 Controller 的 tags 相同时，它们的方法会在一起显示
 
 
 
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 上增加筛选请看上一篇…
 
如果想在文档中屏蔽掉删除用户的接口（user/delete），那么只需要在删除用户的方法上加上 @ApiIgnore 即可。
 
2.用于方法的注解
 
@ApiOperation：方法描述
 
@ApiOperation(value = "创建商户", notes = "开发中")
public Response createMerchants
可以设置的属性如下：
 
 
value：字符串；方法摘要，在路径旁显示
 
 
note：字符串；方法详细描述
 
 
 
tags：字符串数组；对方法进行分类，一个方法可以有多个分类
 
 
 
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 有哪些属性：
 
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 的可以设置的属性如下：
 
name：字符串；参数名
value：字符串；参数的汉字说明、解释
defaultValue：字符串；参数默认值
allowableValues：字符串；限制此参数接收的值，可使用的值或值得范围 
  
(表示是大于，)表示是小于
[表示是大于等于，]表示是小于等于
infinity表示无限大，-infinity表示负无限大
 
allowEmptyValue：true/false；允许参数为空，默认为 false
required：true/false；参数是否必须传
example：字符串；非请求体（body）参数的单个请求示例
examples：Example；参数的举例说明，仅适用于 body 类型。
 
 
关于 @ApiImplicitParam 和 @ApiParm 它俩都能为方法的请求参数做注释，区别有：
 
 
@ApiImplicitParam 可以在方法前使用，而 @ApiParm 只能在参数前使用
@ApiImplicitParam 提供的可设置属性更多，特别是 paramType 很关键
对于 @RequestBody 标识的 Json 字符串，不能使用 @ApiImplicitParam，会出现无法识别的情况 
   
方案一：通过 @ApiParm 对 @RequestBody 的参数进行说明
方案二：直接不对该参数使用注解，将注释的任务交给实体类（@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 有哪些属性
 
code：整形数；相应的状态码
message：字符串；相应消息，例如"电话号码已存在"
response：Class；消息有效负载的可选响应类，对应于响应消息对象的 schema 字段；对于使用通用 Response 的情况，该字段很关键
responseHeaders：ResponseHeader[]；可能响应的 header 列表
responseContainer：String；声明响应的容器，有效值为List,Set,Map，任何其他值都将被忽略
 
3.用于实体类的注解
 
@ApiModel：实体类描述
 
用于请求类或者响应类上，表示一个返回响应数据的信息
 
@ApiModel("创建商户的请求对象")
@Data
@AllArgsConstructor
@NoArgsConstructor
public class CreateMerchantsRequest 
@ApiModel 可以设置的属性有：
 
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 可以设置的属性有：
 
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;
@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;
 
包括配置的完整代码我放到 GitHub 上了，点击这里跳转…
 
                    在上一篇我们详细的介绍了使用 Swagger 时需要做的配置，现在已经能得到一个我们自己想要的页面了但是，这也看不明白啊。。。接口连个中文说明都没有。。。所以，Swagger 提供了很多注解，就是让我们去为每个类、每个接口/参数、每个Model 写解释说明的。1.用于类的注解@Api：资源描述标识这个类是 Swagger 的资源，@Api(tags = "商户相关接口")@RestController@RequestMapping("/merchants")public class Mer
				
https://github.com/ostranme/swagger-ui-themes的所有主题都在扩展中
扩展以在swagger上应用https://github.com/ostranme/swagger-ui-themes中的主题。
支持语言:English
				
Swagger 是一个用于构建、文档化和使用 RESTful Web 服务的开源工具。它提供了一组注解，用于在 API 代码中添加元数据，以便生成交互式 API 文档和客户端 SDK。以下是 Swagger 常用的一些注解：
1. `@Api`：用于描述整个 API 的基本信息，如 API 名称、描述、作者等。
2. `@ApiOperation`：用于描述 API 的一个操作，包括方法名、描述、HTTP 请求方法等。
3. `@ApiParam`：用于描述 API 方法的参数信息，包括参数名、描述、是否必需等。
4. `@ApiModel`：用于描述一个数据模型，即请求或响应的数据结构。
5. `@ApiModelProperty`：用于描述一个数据模型的属性信息，包括属性名、描述、是否必需等。
6. `@ApiResponses`：用于描述 API 方法的响应信息，包括状态码、描述等。
7. `@ApiResponse`：用于描述一个响应的具体信息，包括状态码、描述等。
这些注解可以在不同的地方使用，如在控制器类上、方法上、方法参数上等，以便生成准确的 API 文档和交互式界面。使用这些注解可以使代码更加可读性高，方便生成文档和客户端代码。