Swagger 笔记

Swagger 简介

Open API

Open API规范(OpenAPl Specification)，以前叫做Swagger规范，是REST API的API描述格式。

Open API文件允许描述整个API，包括：

• 每个访问地址的类型，POST 或 GET。
• 每个操作的参数。包括输入输出参数。
• 认证方法。
• 连接信息，声明，使用团队和其他信息。

Open API规范可以使用YAML 或JSON格式进行编写。这样更利于我们和机器进行阅读。

Swagger

Swagger是一套围绕Open API规范构建的开源工具，可以帮助设计，构建，记录和使用REST API。

Swagger工具包括的组件:

• Swagger Editor：基于浏览器编辑器，可以在里面编写ОpenAPI规范。类似 Markdown具有实时预览描述文件的功能。
• Swagger Ul：将Open API规范呈现为交互式API文档。用可视化U展示描述文件。
• Swagger Codegen：将OpenAPI规范生成为服务器存根和客户端库。通过Swagger Codegen可以将描述文件生成 html格式和cwiki形式的接口文档，同时也可以生成多种言语的客户端和服务端代码。
• Swagger Inspector：和Swagger Ul有点类似，但是可以返回更多信息，也会保存请求的实际参数数据。

Springfox

使用Swagger时如果碰见版本更新或迭代时，只需要更改Swagger的描述文件即可。但是在频繁的更新项目版本时很多开发人员认为即使修改描述文件(yml或json)也是一定的工作负担，久而久之就直接修改代码，而不去修改描述文件了，这样基于描述文件生成接口文档也失去了意义。

Marty Pitt编写了一个基于Spring的组件 swagger-springmvc。Spring-fox就是根据这个组件发展而来的全新项目。

Spring-fox是根据代码生成接口文档，所以正常的进行更新项目版本，修改代码而不需要跟随修改描述文件。

Spring-fox利用自身AOP特性，把Swagger集成进来，底层还是Swagger。但是使用起来确方便很多。

所以在实际开发中，都是直接使用spring-fox。

Swagger 配置

pom.xml

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

1、配置基本信息

@Configuration
public class SwaggerConfig {

    @Bean
    // 创建Docket的bean方法
    public Docket getDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(swaggerDemoApiInfo())  // 设置具体的摘要信息
                .select()
                .build();
    }

    // 创建存储了摘要信息的APIInfo信息
    public ApiInfo swaggerDemoApiInfo() {
        return new ApiInfoBuilder()
                    .contact(new Contact("百度","http://www.baidu.com", "xx@163.com"))
                    .title("这里是swagger标题")
                    .description("这里是swagger的描述信息")
                    .version("1.0.0")  // 文档的版本信息
                    .build();
    }

}

2、设置扫描的包

apis()：设置扫描的包路径

@Bean
public Docket getDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(swaggerDemoApiInfo())  
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.baizhi.user.controller"))
        .build();
}

3、自定义注解设置不需要生成接口文档的方法

3.1 自定义注解

建立一个包annotation，在下面建一个annotation！类

@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface NotIncludeSwagger{
}

3.2 添加规则

apis(not(withMethodAnnotation(NotIncludeSwagger.class))) 可以设置生成规则

• public static <T> Predicate<T> not(Predicate<T> predicate)：表示不允许的条件
• withMethodAnnotation：表示此注解是方法级别注解。

@Bean
public Docket getDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(swaggerDemoApiInfo())  
        .select()
        .apis(not(withMethodAnnotation(NotIncludeSwagger.class)))  // 
        .build();
}

3.3 添加 NotIncludeSwagger 注解

在不需要生成接口文档的犯法上面添加 @NotIncludeSwagger 注解后，该方法将不会被Swagger进行生成在接口文档中。

@NotIncludeSwagger
@RequestMapping("/userInfo")
public ... {}

4、设置范围（用的不多）

.paths() 设置满足什么规则的url被生成接口文档，可以用正则表达式进行匹配。

@Bean
public Docket getDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(swaggerDemoApiInfo())  
        .select()
        .paths(allowPaths())
        .build();
}

public Predicate<String> allowPaths() {
    return or(
        regex("/demo/.*")
    );
}

其中

• .：在正则表达式中表示任意字符
• *：表示可以出现n次

Swagger 常用注解

1、@Api

@Api 是类上注解。控制整个类生成接口信息的内容。

• tags：类的名称。可以有多个值，多个值表示多个副本
• description：描述，已过时。

@RestController
@RequestMapping("/people")
@Api(tags = {"mydemo"}, description = "描述")
public class DemoController {}

2、@ApiOperation

@ApiOperation：写在方法上，对方法进行总体描述

• value：接口描述
• notes：提示信息

@ApiOperation(value = "接口描述", notes = "接口提示信息")

3、@ApiParam

@ApiParam：写在方法参数前面。用于对参数进行描述或说明是否为必填项等说明。

• name：参数名称（不建议改）
• value：参数描述
• required：是否是必须

public People getPeople(Integer id, @ApiParam(value="姓名", required=true) String name, String address)

4、@ApiModel

@ApiModel：是类上注解，主要应用Model，也就是说这个注解一般都是写在实体类上。

• value：名称
• description：描述

@ApiModel(value = "人类", description = "描述")
public class People {}

5、@ApiModelProperty

@ApiModelProperty ：可以用在方法或属性上。用于当对象作为参数是定义这个字段的内容。

• value：名称
• name：重写属性名
• required：是否是必须的
• example：实例内容
• hidden：是否隐藏

@ApiModelProperty(value = "姓名", name = "name", required = true, example = "zhang'san")
private String name;

6、@ApiIgnore

@Apilgnore用于方法或类或参数上，表示这个方法或类被忽略。和之前讲解的自定义注解@NotIncludeSwagger效果类似。只是这个注解是Swagger内置的注解，@NotIncludeSwagger是我们自定义的注解。

7、@ApiImplicitParam

@ApilmplicitParam用在方法上，表示单独的请求参数，总体功能和@ApiParam类似。

• name：属性名
• value：描述
• required：是否是必须的
• paramType：属性类型
• dataType：数据类型

@PostMapping("/getPeople")
@ApiImplicitParam(name = "address", value = "地址", required = true, paramType = "query", dataType = "string")
public People getPeople(Integer id, @ApiParam(value = "姓名", required = true)String name, String address)