Spring Boot 集成 Swagger

前言

为了完成项目自带文档的需求，花了一定的时间研究Spring Boot集成Swagger。看了官方文档和一些博客，差不多搭出一个比较通用的架子。

文末会分享出案例项目。

基本概述

本文使用Spring Boot+Spring Fox的方式集成Swagger框架。

案例

引入依赖

<properties>
    <swagger.version>2.7.0</swagger.version>
</properties>
<dependencies>
    <!-- swagger2 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>${swagger.version}</version>
    </dependency>
    <!-- swagger2 ui -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>${swagger.version}</version>
    </dependency>
</dependencies>

Swagger 配置

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.switchvov.swagger"))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }
<span class="hljs-comment">/**
 * 配置认证模式
 */</span>
<span class="hljs-keyword">private</span> List&lt;ApiKey&gt; <span class="hljs-title function_">securitySchemes</span><span class="hljs-params">()</span> {
    <span class="hljs-keyword">return</span> newArrayList(<span class="hljs-keyword">new</span> <span class="hljs-title class_">ApiKey</span>(<span class="hljs-string">"Authorization"</span>, <span class="hljs-string">"Authorization"</span>, <span class="hljs-string">"header"</span>));
}

<span class="hljs-comment">/**
 * 配置认证上下文
 */</span>
<span class="hljs-keyword">private</span> List&lt;SecurityContext&gt; <span class="hljs-title function_">securityContexts</span><span class="hljs-params">()</span> {
    <span class="hljs-keyword">return</span> newArrayList(SecurityContext.builder()
            .securityReferences(defaultAuth())
            .forPaths(PathSelectors.any())
            .build());
}

<span class="hljs-keyword">private</span> List&lt;SecurityReference&gt; <span class="hljs-title function_">defaultAuth</span><span class="hljs-params">()</span> {
    <span class="hljs-type">AuthorizationScope</span> <span class="hljs-variable">authorizationScope</span> <span class="hljs-operator">=</span> <span class="hljs-keyword">new</span> <span class="hljs-title class_">AuthorizationScope</span>(<span class="hljs-string">"global"</span>, <span class="hljs-string">"accessEverything"</span>);
    AuthorizationScope[] authorizationScopes = <span class="hljs-keyword">new</span> <span class="hljs-title class_">AuthorizationScope</span>[<span class="hljs-number">1</span>];
    authorizationScopes[<span class="hljs-number">0</span>] = authorizationScope;
    <span class="hljs-keyword">return</span> newArrayList(<span class="hljs-keyword">new</span> <span class="hljs-title class_">SecurityReference</span>(<span class="hljs-string">"Authorization"</span>, authorizationScopes));
}

<span class="hljs-comment">/**
 * 项目信息
 */</span>
<span class="hljs-keyword">private</span> ApiInfo <span class="hljs-title function_">apiInfo</span><span class="hljs-params">()</span> {
    <span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> <span class="hljs-title class_">ApiInfoBuilder</span>()
            .title(<span class="hljs-string">"Swagger测试项目 RESTful APIs"</span>)
            .version(<span class="hljs-string">"1.0"</span>)
            .build();
}

}

配置方式

基本概述

Swagger 官方 Wiki 注解
swagger2 常用注解说明
swagger 注释 API 详细说明

PS：以上几篇文章已经将Swagger注解的使用方式及作用阐述的非常清楚了。这里只给出代码案例。

PS：springfox-swagger2:2.7.0已经支持泛型返回对象。
注意：千万不要在@ApiOperation注解里限定response()，让框架推断类型就行了。

控制器

@RestController
@RequestMapping(value = "/user", produces = "application/json")
@Api(value = "User", tags = {"User"}, description = "用户相关")
public class UserController {
    @Autowired
    private UserService userService;
<span class="hljs-meta">@GetMapping("/{id}")</span>
<span class="hljs-meta">@ApiOperation(value = "使用ID查询用户")</span>
<span class="hljs-meta">@ApiImplicitParams({
        @ApiImplicitParam(value = "ID", name = "id", dataType = "int", paramType = "path", required = true, defaultValue = "1")
})</span>
<span class="hljs-meta">@ApiResponses({
        @ApiResponse(code = 400, message = "请求参数有误"),
        @ApiResponse(code = 401, message = "未授权"),
        @ApiResponse(code = 403, message = "禁止访问"),
        @ApiResponse(code = 404, message = "请求路径不存在"),
        @ApiResponse(code = 500, message = "服务器内部错误")
})</span>
<span class="hljs-keyword">public</span> ResponseResult&lt;User&gt; <span class="hljs-title function_">getById</span><span class="hljs-params">(<span class="hljs-meta">@PathVariable("id")</span> Integer id)</span> {
    <span class="hljs-type">User</span> <span class="hljs-variable">user</span> <span class="hljs-operator">=</span> userService.getById(id);
    <span class="hljs-keyword">return</span> ResponseResult.successWithData(user);
}

<span class="hljs-meta">@PostMapping("")</span>
<span class="hljs-meta">@ApiOperation(value = "创建用户")</span>
<span class="hljs-meta">@ApiResponses({
        @ApiResponse(code = 400, message = "请求参数有误"),
        @ApiResponse(code = 401, message = "未授权"),
        @ApiResponse(code = 403, message = "禁止访问"),
        @ApiResponse(code = 404, message = "请求路径不存在"),
        @ApiResponse(code = 500, message = "服务器内部错误")
})</span>
<span class="hljs-keyword">public</span> ResponseResult&lt;User&gt; <span class="hljs-title function_">createUser</span><span class="hljs-params">(<span class="hljs-meta">@Validated</span> <span class="hljs-meta">@RequestBody</span> User user)</span> {
    <span class="hljs-type">User</span> <span class="hljs-variable">dbUser</span> <span class="hljs-operator">=</span> userService.createUser(user);
    <span class="hljs-keyword">return</span> ResponseResult.successWithData(dbUser);
}

}

统一响应类

@ApiModel(description = "响应对象")
public class ResponseResult<T> {
    private static final int SUCCESS_CODE = 0;
    private static final String SUCCESS_MESSAGE = "成功";
<span class="hljs-meta">@ApiModelProperty(value = "响应码", name = "code", required = true, example = "" + SUCCESS_CODE)</span>
<span class="hljs-keyword">private</span> <span class="hljs-type">int</span> code;

<span class="hljs-meta">@ApiModelProperty(value = "响应消息", name = "msg", required = true, example = SUCCESS_MESSAGE)</span>
<span class="hljs-keyword">private</span> String msg;

<span class="hljs-meta">@ApiModelProperty(value = "响应数据", name = "data")</span>
<span class="hljs-keyword">private</span> T data;

<span class="hljs-comment">// 省略get、set方法等等，详见源代码</span>

}

用户 Model

PS：用户 model 使用了lombok、jpa、validator，只需要关注@Api开头的注解就行了。

@Data
@Entity(name = "users")
@ApiModel(description = "用户 Model")
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    @Null(message = "id 必须为空")
    @ApiModelProperty(value = "用户 ID", name = "id")
    private Integer id;
<span class="hljs-meta">@Column</span>
<span class="hljs-meta">@NotBlank(message = "用户名不能为空")</span>
<span class="hljs-meta">@ApiModelProperty(value = "用户名", name = "username", required = true, example = "zhaoliu")</span>
<span class="hljs-keyword">private</span> String username;

<span class="hljs-meta">@Column</span>
<span class="hljs-meta">@NotBlank(message = "密码不能为空")</span>
<span class="hljs-meta">@ApiModelProperty(value = "密码", name = "password", required = true, example = "123456")</span>
<span class="hljs-keyword">private</span> String password;

}

文档界面

源码

GitHub：swagger-demo

参考信息

• SpringFox 官网
• Swagger 官方 Wiki 注解
• Spring Boot 中使用 Swagger2 构建强大的 RESTful API 文档
• 第四章 springboot + swagger
• Spring 启动 RESTful API 文档使用 Swagger 2
• swagger2 常用注解说明
• swagger 注释 API 详细说明
• Swagger2 添加 HTTP head 参数
• Swagger2 非全局、无需重复输入的 Head 参数（Token）配置

分享并记录所学所见