Swagger 特点

  • 世界上最流行的Api框架
  • RestFul Api 文档在线自动生成工具 -> Api文档与API定义同步更新
  • 支持多种语言（Java，PHP…)

官网：https://swagger.io

在项目中使用Swagger需要springbox；

  • swagger2
  • ui

SpringBoot 集成 Swagger

  1. 新建 SpringBoot-web 项目
  2. 导入相关依赖
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>
<!-- 3.0以后版本要添加boot-starter -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
  1. 编写一个 Hello 工程
  2. 配置Swagger-config
1
2
3
4
5
6
7
8
9
10
package com.at0m.swagger.config;

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2  // 开启Swagger2（3.0以后版本不需要添加）
public class SwaggerConfig {
  
}
  1. 测试运行访问页面
1
2
3
4
3.0以前版本
http://localhost:8080/swagger-ui.html
3.0及以后版本
http://localhost:8080/swagger-ui/index.html

配置 Swagger 信息

Swagger 配置（在config下配置）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// 配置Swagger的Docket的bean实例
@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo());
}

// 配置Swagger信息 apiInfo
private ApiInfo apiInfo(){
    // 作者信息
    Contact DEFAULT_CONTACT = new Contact("AT0M", "http://0x4154304d.github.io", "shipf8023@163.com");
    return new ApiInfo("AT0M的Swagger的API文档",
            "无限进步",
            "v1.0",
            "http://0x4154304d.github.io",
            DEFAULT_CONTACT,
            "Apache 2.0",
            "http://www.apache.org/licenses/LICENSE-2.0",
            new ArrayList());
}

Swagger 配置扫描接口

Docket.select()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// 配置Swagger的Docket的bean实例
@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            // RequestHandlerSelectors 配置要扫描接口的方式
            // basePackage 指定要扫描的包
            // any 扫描全部
            // none 不扫描
            // withClassAnnotation 扫描类上的注解，参数是一个注解的反射对象
            // withMethodAnnotation 扫描方法上的注解
            .apis(RequestHandlerSelectors.basePackage("com.at0m.swagger.controller"))
            // 过滤路径
            .paths(PathSelectors.ant("/hello/**"))
            .build(); // 工厂模式
}

配置是否启动swagger

1
2
3
4
5
6
7
8
9
10
11
// 配置Swagger的Docket的bean实例
@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            // 是否启用swagger？如果为false，swagger不能在浏览器中访问
            .enable(false)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.at0m.swagger.controller"))
            .build(); // 工厂模式
}

配置swagger使用环境

在生产环境中使用，在发布的时禁用

  • 判断是否为生产环境 flag = false
  • 注入enable()值
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// 配置Swagger的Docket的bean实例
@Bean
public Docket docket(Environment environment) {
    // 获取项目当前环境
    // 设置要返回的Swagger环境
    Profiles profiles = Profiles.of("dev", "test");
    // 通过environment.acceptsProfiles 判断是否处于监听的环境
    boolean flag = environment.acceptsProfiles(profiles);

    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            // 是否启用swagger？如果为flase，swagger不能在浏览器中访问
            .enable(flag)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.at0m.swagger.controller"))
            .build(); // 工厂模式
}

配置文档 API 分组

1
.groupName("at0m")

配置多个分组，多个Docket实例即可

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}

@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}

@Bean
public Docket docket3(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}

@Bean
public Docket docket4(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("D");
}

Swagger API Annotation

@Api

该注解将一个Controller（Class）标注为一个Swagger资源（API）。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。该注解包含以下几个重要属性：

  • tags
    API分组标签。具有相同标签的API将会被归并在一组内展示，如果设置tags，value值将会被覆盖。
  • value
    如果tags没有定义，value将作为Api的tags使用
  • description
    API的详细描述，在1.5.X版本之后不建议使用，目前在3.0.0版本中依然可以使用

@ApiOperation

在指定的（路由）路径上，对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。此注解的属性有：

  • value

    对操作的简单说明，长度为120个字母，60个汉字。

  • notes

    对操作的详细说明。

  • httpMethod

    HTTP请求的动作名，可选值有：”GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”。

  • code

    默认为200，有效值必须符合标准的HTTP Status Code Definitions。

@ApiImplicitParams

注解ApiImplicitParam的容器类，以数组方式存储。

@ApiParam

增加对参数的元信息说明。这个注解只能被使用在JAX-RS 1.x/2.x的综合环境下。其主要的属性有：

  • required
    是否为必传参数
  • value
    参数简短说明

@ApiResponses

注解@ApiResponse的包装类，数组结构。即使需要使用一个@ApiResponse注解，也需要将@ApiResponse注解包含在注解@ApiResponses内

@ApiResponse

描述一个操作可能的返回结果。当REST API请求发生时，这个注解可用于描述所有可能的成功与错误码。可以用，也可以不用这个注解去描述操作的返回类型，但成功操作的返回类型必须在@ApiOperation中定义。如果API具有不同的返回类型，那么需要分别定义返回值，并将返回类型进行关联。但Swagger不支持同一返回码，多种返回类型的注解。注意：这个注解必须被包含在@ApiResponses注解中。

  • code
    HTTP请求返回码。有效值必须符合标准的HTTP Status Code Definitions。

  • message
    易于理解的文本消息

  • response
    返回类型信息，必须使用完全限定类名，比如“com.at0m.Student.class”。

  • responseContainer
    如果返回类型为容器类型，可以设置相应的值。有效值为 "List", "Set" or "Map"，其他任何无效的值都会被忽略。

controller

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
package com.at0m.swagger.controller;

import com.at0m.swagger.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

@Api(value = "hello 控制类", description = "What？？？")
@RestController
public class HelloController {

    @GetMapping(value = "/hello")
    public String hello(){
        return "hello";
    }

    // 只要接口中的返回值存在实体类，它就会扫描到swagger中
    @PostMapping(value = "/user")
    public User user(){
        return new User();
    }

    // Operation接口，不是放在类上，是方法
    @ApiOperation(value = "Hello控制类 ApiOperation使用", httpMethod = "GET", code = 200)
    @GetMapping("/hello2")
    public String hello(@ApiParam("用户名") String userName){
        return "hello" + userName;
    }

    @ApiOperation("Post测试类")
    @PostMapping("/postt")
    public User postt(@ApiParam("用户名") User user){
        int i = 5/0;
        return user;
    }
}

Swagger Model Annotation

@ApiModel

提供对Swagger model额外信息的描述。在标注@ApiOperation注解的操作内，所有的类将自动被内省（introspected），但利用这个注解可以做一些更加详细的model结构说明。主要属性有：

  • value
    model的别名，默认为类名
  • description
    model的详细描述

@ApiModelProperty

对model属性的注解，主要的属性值有：

  • value
    属性简短描述
  • example
    属性的示例值
  • required
    是否为必须值

实体类配置

1
2
3
4
5
6
7
8
9
10
11
12
13
package com.at0m.swagger.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String userName;
    @ApiModelProperty("密码")
    public String password;
}

总结：

  1. 通过Swagger给一些比较难理解的属性或者接口，增加注释信息

  2. 接口文档实时更新

  3. 可以在线测试

注意！！！：正式发布的时候，关闭Swagger！！！出于安全考虑。且节省运行内存。