Swagger2使用

发表于 | 分类于 |

一、介绍

Swagger2提供了在线文档的查阅和测试功能。利用Swagger2很容易构建阻STful风格的API，在SpringBoot中集成Swagger2。

二、配置

1、Gradle安装包

1
2
compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'
compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'

第三方开发更符合阅读的ui，可以用来代替springfox-swagger-ui
swagger-ui-layer

1
compile 'com.github.caspar-chen:swagger-ui-layer:1.1.3'

2、配置文件

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
package cn.pccpa.ims.launcher.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.context.request.async.DeferredResult;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class Swagger2 {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .genericModelSubstitutes(DeferredResult.class)
                .useDefaultResponseMessages(false)
                .forCodeGeneration(false)
                .pathMapping("/")
                .select()
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XXXOA系统API文档")
                .version("1.0")
                .build();
    }
}

3、启动项

增加@EnableSwagger2注解

4、启动项目

打开http://localhost:8080/swagger-ui.html#查看

官方界面

官方界面

人性化界面

第三方优化界面

三、Restful接口配置

1、常用注解

  • @Api
    Marks a class as a Swagger resource.
  • @ApiModel
    Provides additional information about Swagger models.
  • @ApiModelProperty
    Adds and manipulates data of a model property.
  • @ApiOperation
    Describes an operation or typically a HTTP method against a specific path.
  • @ApiParam
    Adds additional meta-data for operation parameters.
  • @ApiImplicitParam
    Represents a single parameter in an API Operation.
  • @ApiImplicitParam
    A wrapper to allow a list of multiple ApiImplicitParam objects.
    具体请打开Quick Annotation Overview有详细说明

2、API地址

官方地址http://${host}:${port}/swagger-ui.html

新UI地址http://${host}:${port}/docs.html（推荐）

四、实例

1、Controller层

需要对controller加上@Api注解，各方法添加@ApiOperation注解，方法的参数添加@ApiParam注解，具体对应请看下面例子

注意

@ApiImplicitParam注解遇到@RequestBody将不起效，作者已经注意到此bug，预计将在3版本后修复，请将遇到的model还是依旧进行注解标示
使用@ApiParam注解无bug

1
2
3
4
5
6
7
8
9
10
11
12
13
14
@Api(value="hr.recruit", tags="人力招聘简历接口")
@RestController
@RequestMapping("/api/pc/recruit/resume")
public class ResumeController {

    @ApiOperation(value="获取简历表信息", notes = "简历表信息")
    @PostMapping("/list/tableData/{menuId}")
    public PageSuit getPostList(@ApiParam(name="menuId",value="菜单Id",required=true) @PathVariable("menuId") String menuId,
                                @ApiParam(name="pageParam",value="高级搜索参数",required=true) @RequestBody ListPageParam<ResumeSelection> pageParam) throws IllegalAccessException {
        String currentEId = employeeService.getCurrentUser().geteId();
        return resumeService.getResumeList(currentEId, menuId, pageParam);
    }

}

或者将以下注解写在请求函数上面

1
2
3
4
5
@ApiOperation(value = "获取简历表信息", notes = "简历表信息")
@ApiImplicitParams({
        @ApiImplicitParam(name = "menuId", value = "菜单Id", required = true, dataType = "String", paramType = "form"),
        @ApiImplicitParam(name = "pageParam", value = "高级搜索参数", required = true, dataType = "ListPageParam<ResumeSelection>", paramType = "form")
})

2、Model层

当方法的参数或返回类型涉及到类（Entity、Dto等），需要对类添加@ApiModel注解，对每一个变量添加@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
@ApiModel(value="简历搜索对象")
public class ResumeSelection {

    @ApiModelProperty(value="用户名",name="username")
    private String username;

    @ApiModelProperty(value="邀约情况",name="inviteStatus")
    private Integer[] inviteStatus;

    @ApiModelProperty(value="是否注册",name="isRegister")
    private Integer isRegister;

    @ApiModelProperty(value="岗位名称",name="jobName")
    private String jobName;

    @ApiModelProperty(value="简历状态",name="resumeStatus")
    private Integer[] resumeStatus;

    @ApiModelProperty(value="所属机构id",name="areaId")
    private String areaId;

    @ApiModelProperty(value="招聘类型",name="recruitStyle")
    private Integer[] recruitStyle;

    //下面略
}

参考文章

Annotations 1.5.X
swagger-ui-layer