注:本文为学习时记录的笔记，内容尚浅，后续有时间可能会完善

整合swagger

第一种方式：使用第三方依赖

1.在pom.xml文件中添加第三方swagger依赖

<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.7.0.RELEASE</version>
</dependency>

2、在Spring Boot项目的启动类上添加@EnableSwagger2，启动Swagger(注意，从swagger-spring-boot-starter2.0版本以后，不需要添加@EnableSwagger2注解)

3、github.com/SpringForAl…

第二种方式：使用官方依赖

1.在pom.xml文件中添加swagger相关依赖

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.2.2</version>
</dependency>
<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.2.2</version>
</dependency>
<dependency>
        <groupId>org.codehaus.jackson</groupId>
        <artifactId>jackson-core-asl</artifactId>
        <version>1.9.13</version>
</dependency>

第一个是API获取的包

第二是官方给出的一个ui界面，这个界面可以自定义，默认是官方的

第三个是测试数据以JSON格式返回的依赖包

修改配置信息

示例配置bootstrap.yaml:

swagger:
  title: "xxxx系统"    <!--文档标题-->
  description: "该系统xxxx"    <!--文档描述-->
  base-package: com.xuecheng.content   <!--swagger扫描的基础包-->
  enabled: true    <!--用于开关swagger的配置-->
  version: 1.0.0

重启项目，访问web界面

访问如下地址

http://ip:端口/swagger-ui.html

swagger常用注解

1.用于类的注解

@Api：资源描述

标识这个类是 Swagger 的资源，

@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 功能强大

2.用于方法的注解

@ApiOperation：方法描述

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

可以设置的属性如下：

value：字符串；方法摘要，在路径旁显示

note：字符串；方法详细描述

tags：字符串数组；对方法进行分类，一个方法可以有多个分类

response：Class；设置当前请求的返回值类型，String.class；会覆盖自动识别的返回类型，一般用不上

responseContainer：字符串；说明包装的容器，默认情况下，有效值为 List、Set、Map；在定义通用 Response 后，一般用不上

@ApiParam：参数描述

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

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

可以设置的属性如下：

name：字符串；参数名

value：字符串；参数的汉字说明、解释

defaultValue：字符串；参数默认值

allowableValues：字符串；限制此参数接收的值，可使用的值或值的范围，(表示是大于，)表示是小于， [表示是大于等于，]表示是小于等于，infinity表示无限大，-infinity表示负无限大

allowEmptyValue：true/false；允许参数为空，默认为 false

required：true/false；参数是否必须传

example：字符串；非请求体（body）参数的单个请求示例

examples：Example；参数的举例说明，仅适用于 body 类型。

httpMethod：字符串；指定请求方式，比如 GET、POST、PUT

consumes：字符串；指定处理请求的提交内容类型(Content-Type)，例如 application/json

produces：字符串；指定返回的内容类型，即仅当请求头的 Accept 类型中包含该指定类型才返回，例如:application/json

@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表示负无限大