swagger2自动生成API文档

发表于 分类于 阅读次数： 本文字数： 516 阅读时长 ≈ 1 分钟

Swagger2 是一个规范和完整的框架，用于生成、描述、调用和可视化Restful风格的web服务，现在我们使用spring boot 整合它。

引入pom依赖
1
2
3
4
5
6
7
8
9
10
11
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<!--界面支持-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
编写Swagger2配置文件
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.kuang.git;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2Configuration {

    //api接口扫描包路径
    public static final String SWAGGER2_SCAN_BASE_PACKAGE = "com.kuang.git";
    public static final String VERSION = "1.0.0";

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(swagger2ApiTest())
                .select()
                .apis(RequestHandlerSelectors.basePackage(SWAGGER2_SCAN_BASE_PACKAGE))
                //根据url路径设置哪些请求加入文档、忽略哪些请求
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo swagger2ApiTest() {
        return new ApiInfoBuilder()
                .title("SWAGGER2")//设置文档标题
                .description("SWAGGER2 API文档测试")//文档描述
                .version(VERSION)//文档版本
                .termsOfServiceUrl("http://www.baidu.com")//设置文档的License信息
                .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
package com.kuang.git;

import com.alibaba.fastjson.JSONException;
import com.alibaba.fastjson.JSONObject;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;

import java.text.ParseException;
import java.util.Date;

@Api(description = "Swagger2 时间测试")
@Controller
@RequestMapping("/swagger2")
public class Swagger2Web {

    @ResponseBody
    @RequestMapping(value = "/time",method = RequestMethod.GET)
    @ApiOperation(value = "获取系统时间",notes = "获取系统时间",produces = "aplication/json")
    public JSONObject SwaggerTest() throws ParseException, JSONException {
        JSONObject json = new JSONObject();
        //标准时间
        String res = (new Date()).toString();
        json.put("Date",res);
        return json;
    }
}
常用注释说明

@Api 注解可以用来标记 Controller 的功能

@ApiOperation 注解用来标记一个方法的作用

@ApilmplicitParam 注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入

@ApilmplicitParams 如果有多个参数，则需要使用多个 @ApilmplicitParam 注解来描述， 多个 @ApilmplicitParam 注解需要放在一个 @ApilmplicitParams 注解中

@ApiModel 如果参数是一个对象，则需要在对象所在的类上加上此注解

@ApiModelProperty 如果参数是一个对象，则需要在对应的属性上加上此注解，还需要在对象所在的类上加上 @ApiModel

@ApiIgnore 注解标识此参数可以忽略

上面的配置完成之后就已经集成完成。启动项目之后，浏览器输入http://127.0.0.1:8083/swagger-ui.html访问。