高端大气的api文档 swagger2 （springboot）

前言

本贴是小的我自己踩坑学习贴，并不是大佬的教学贴各位看官且看且交流学习共同进步。

背景

在日常的开发中是否有如下的烦恼：

1. 给前端提供后台数据接口时需要提供对应的文档！！；
2. 跟其他部门或者单位协作时需要提供接口文档！！！；
3. 南北向对外的公共方法需要文档！！！！；
   ps:文档文档全是文档文笔不好排版不会染色贼差 我太难了

于是这个时候就需要一个能自动生成文档的东东了还能直接测试 给劲儿

预览效果

内容都是测试用的就看看样式效果就行了难得造一个体面的测试数据了毕竟我太懒了。。。

食用步骤

直接上干货

1. pom配置

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

2. springboot的配置类

// 配置类
@Configuration
@EnableSwagger2
public class Swagger2Configuration {
    //api接口包扫描路径
    public static final String SWAGGER_SCAN_BASE_PACKAGE = "com.example.demo.biz.controller";
    //下面需要用到的版本变量
    public static final String VERSION = "1.0.0";
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                .paths(PathSelectors.any()) // 可以根据url路径设置哪些请求加入文档，忽略哪些请求
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("测试工程接口清单") //设置文档的标题
                .description("API 接口文档") // 设置文档的描述
                .version(VERSION) // 设置文档的版本信息-> 1.0.0 Version information
                .termsOfServiceUrl("http://www.baidu.com") // 设置文档的信息
                .build();
    }
}

3. 具体食用

预览图中的测试模型

@ApiModel(description = "测试模型")
public class BaseModel {
    @ApiModelProperty(value = "姓名")
    private String name;
    @ApiModelProperty(value = "年龄")
    private int age;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }
}

controller：

@Api(description = "第一个测试controller接口类")
@RestController
public class TestApiController {

    @ApiOperation(value = "测试方法test", notes = "这是用来测试swagger2 框架得测试接口方法", produces = "application/json")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "s", value = "传入基础模型", paramType = "body", required = true, dataType = "BaseModel"),
    })
    @RequestMapping(value = "test", method = {RequestMethod.POST})
    @ResponseBody
    public BaseModel getString(@RequestBody BaseModel s) {
        s.setAge(s.getAge() + 1);
        System.out.println(s);
        return s;
    }
}

标签解释如下：

标签	详解
@Api	修饰整个类，描述Controller的作用
@ApiOperation	描述一个类的一个方法，或者说一个接口
@ApiParam	单个参数描述
@ApiModel	用对象来接收参数
@ApiProperty	用对象接收参数时，描述对象的一个字段
@ApiResponse	HTTP响应其中1个描述
@ApiResponses	HTTP响应整体描述
@ApiIgnore	使用该注解忽略这个API
@ApiError	发生错误返回的信息
@ApiImplicitParam	描述一个请求参数，可以配置参数的中文含义，还可以给参数设置默认值
@ApiImplicitParams	描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表

在操作中 ApiImplicitParam 又有很多参数其中举例几个如下：

参数	详解
name	参数名称
value	参数解释
paramType	参数应该放在请求的什么地方例如： header–>放在请求头。请求参数的获取：@RequestHeader(代码中接收注解) query–>用于get请求的参数拼接。请求参数的获取：@RequestParam(代码中接收注解) path（用于restful接口）–>请求参数的获取：@PathVariable(代码中接收注解) body–>放在请求体。请求参数的获取：@RequestBody(代码中接收注解)
dataType	参数的数据类型
. . .	. . .

4. 访问生成的api文档

swagger2 默认的请求路径是项目地址 后面加上 swagger-ui.html 请求就可以了例如：
这里我项目的根目录是 http://localhost:8080
so
api文档访问地址就是这个啦：http://localhost:8080/swagger-ui.html

当然有集成权限校验框架的童鞋例如 shiro , spring security 就需要把这个请求地址放开否则会直接被拦截无法打到这个效果啦。