号称"最强API文档工具"的Swagger到底厉害在哪-工具盒子

# （一）引言 {#一-引言}

我的第一份工作用的技术架构比较老，在写Api接口的时候都是自己手动写一个接口文档。但是一旦接口多了，这些文档就很难管理。我现在的工作在应用层面使用了SpringBoot，项目种也大量用到了Swagger2。我个人感觉Swagger的厉害之处在于极少的配置和几个注解就可以生成一份完善的技术文档，将维护文档和修改代码整合为一体，节省了大量时间。

# （二）Swagger与SpringBoot的整合 {#二-swagger与springboot的整合}

Swagger的使用很简单，这里通过一个简单的例子进行展示

# （2.1）引入依赖 {#_2-1-引入依赖}

先需要创建一个Springboot项目，并引入Swagger2的相关依赖：

<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
2
3
4
5
6
7
8
9
10

# (2.2)创建实体类 {#_2-2-创建实体类}

因为项目比较简单，实现User类的增删改查API接口，因此全部放在一个文件夹之下，创建User.java，这里用到了swagger对于实体类的两个注解@ApiModel和@ApiModelProperty，分别表示实体类的含义以及属性的含义。

@Data
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("id")
    private Long id;
    @ApiModelProperty("name")
    private String name;
    @ApiModelProperty("age")
    private Integer age;
}

1
2
3
4
5
6
7
8
9
10

# (2.3)创建Swagger2配置文件 {#_2-3-创建swagger2配置文件}

swagger的配置主要基本的展示信息以及扫描信息，其中@Configuration注解使得Spring启动该配置类，@EnableSwagger2启动Swagger2

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                //创建api基本信息
                .apiInfo(apiInfo())
                .select()
                //RequestHandlerSelectors.basePackage指定扫描的包路径
                //RequestHandlerSelectors.any():扫描全部
                //RequestHandlerSelectors.none():不扫描
                //RequestHandlerSelectors.withClassAnnotation():扫描类上的注解
                //RequestHandlerSelectors.withMethodAnnotation():扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.javayz.swaggerdemo.controller"))
                //过滤什么路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Java鱼仔的SwaggerAPI文档")
                .description("你会累因为你在走上坡路")
                .termsOfServiceUrl("https://blog.csdn.net/qq_41973594")
                .contact(new Contact("Java鱼仔","https://blog.csdn.net/qq_41973594","974474148@qq.com"))
                .version("1.0")
                .build();
    }
}

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

ApiInfo中的参数如下所示：

# （2.4）创建Controller，定义API {#_2-4-创建controller-定义api}

@Api(value = "用户信息管理")
@RestController
@RequestMapping(value="/users")
public class UserController {

    //创建一个线程安全的map
    static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>());

    //获取User列表
    @ApiOperation(value="获取用户列表", notes="")
    @RequestMapping(value={""}, method= RequestMethod.GET)
    public List<User> getUserList() {
        List<User> r = new ArrayList<User>(users.values());
        return r;
    }
    //根据用户id删除用户
    @ApiOperation(value = "删除用户",notes = "根据id删除用户")
    @ApiImplicitParam(name = "id",value = "输入用户id",required = true,dataType = "Long")
    @RequestMapping(value = "/{id}",method = RequestMethod.DELETE)
    public String DeleteList(@PathVariable Long id){
        users.remove(id);
        return "success";
    }
    //创建用户
    @ApiOperation(value="创建用户", notes="根据User对象创建用户")
    @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    @RequestMapping(value="", method=RequestMethod.POST)
    public String postUser(@RequestBody User user) {
        users.put(user.getId(), user);
        return "success";
    }
    //根据用户id获取用户信息
    @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
    @RequestMapping(value="/{id}", method=RequestMethod.GET)
    public User getUser(@PathVariable Long id) {
        return users.get(id);
    }
    //根据指定id更新对象
    @ApiOperation(value="更新用户详细信息", notes="根据url的id来指定更新对象，并根据传过来的user信息来更新用户详细信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
            @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    })
    @RequestMapping(value="/{id}", method=RequestMethod.PUT)
    public String putUser(@PathVariable Long id, @RequestBody User user) {
        User u = users.get(id);
        u.setName(user.getName());
        u.setAge(user.getAge());
        users.put(id, u);
        return "success";
    }
}

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
41
42
43
44
45
46
47
48
49
50
51
52
53

以上代码乍一看有很多的配置文件，其实实际使用起来很简单，通过@Api、@ApiOperation注解来给API增加说明、通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明。注解各个参数的功能如下：

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
 
@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"
 
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值
        
@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类
 
@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性

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