降龙十八掌之SpringBoot 使用Swagger2打造在线接口文档

序言：编写和维护接口文档是每一个程序员的职责，根据Swagger2能够快速帮助咱们编写最新的API接口文档，不再用担忧开会前仍忙于整理各类资料了，间接提高了团队开发的沟通效率。此外，本教程还额外提供了UI汉化教程，去除阅读官方英文界面的烦恼。（目前Swagger汉化教程是找不到的，由于官方手册实在写得太烂。。）

SpringBoot + Swagger2 UI界面-汉化教程 1.默认的英文界面UI 想必不少小伙伴都曾经使用过Swagger，可是打开UI界面以后，倒是下面这样的画风，纯英文的界面并不太友好，做为国人仍是习惯中文界面。

号称世界最流行的API工具总不应不支持国际化属性吧，楼主在官方使用手册找到关于本地化和翻译的说明：

也就是说，只要添加翻译器和对于的译文JS就能够显示中文界面了。（使用IDEA 双击Shift 快速找到swagger-ui.html 入口文件）

注：对静态资源的存放路径有疑惑的请戳：SpringBoot项目结构说明

2.定制中文界面 2.1 添加首页和译文 重点来了，在src/main/resources目录下建立META-INF\resources目录，而后建立一个名称为"swagger-ui.html" 的HTML文件。如图：

注意文件名不要起错，接下来将下面这段内容原封不动的拷贝进去。

swagger

Explore

OK 大功告成 咱们访问 http://localhost:8080/swagger-ui.html 看看显示效果：

注：关于国际化，直接在Github下载好Swagger-UI的源码，将swagger-ui.html替换成上文，直接发布到Maven私服仓库，使用效果更佳。

2.2 更详细的译文翻译（非必需） 若是想进一步调整译文，能够在META-INF\resources\webjars\springfox-swagger-ui\lang 目录下添加zh-cn.js文件.

而后在译文（zh-cn.js ）根据我的喜爱来添加翻译内容，以下

'use strict'; /* jshint quotmark: double */ window.SwaggerTranslator.learn({ "Warning: Deprecated":"警告：已过期", "Implementation Notes":"实现备注", "Response Class":"响应类", "Status":"状态", "Parameters":"参数", "Parameter":"参数", "Value":"值", "Description":"描述", "Parameter Type":"参数类型", "Data Type":"数据类型", "Response Messages":"响应消息", "HTTP Status Code":"HTTP状态码", "Reason":"缘由", "Response Model":"响应模型", "Request URL":"请求URL", "Response Body":"响应体", "Response Code":"响应码", "Response Headers":"响应头", "Hide Response":"隐藏响应", "Headers":"头", "Try it out!":"试一下！", "Show/Hide":"显示/隐藏", "List Operations":"显示操做", "Expand Operations":"展开操做", "Raw":"原始", "can't parse JSON. Raw result":"没法解析JSON. 原始结果", "Example Value":"示例", "Click to set as parameter value":"点击设置参数", "Model Schema":"模型架构", "Model":"模型", "apply":"应用", "Username":"用户名", "Password":"密码", "Terms of service":"服务条款", "Created by":"建立者", "See more at":"查看更多：", "Contact the developer":"联系开发者", "api version":"api版本", "Response Content Type":"响应Content Type", "Parameter content type:":"参数类型:", "fetching resource":"正在获取资源", "fetching resource list":"正在获取资源列表", "Explore":"浏览", "Show Swagger Petstore Example Apis":"显示 Swagger Petstore 示例 Apis", "Can't read from server. It may not have the appropriate access-control-origin settings.":"没法从服务器读取。可能没有正确设置access-control-origin。", "Please specify the protocol for":"请指定协议：", "Can't read swagger JSON from":"没法读取swagger JSON于", "Finished Loading Resource Information. Rendering Swagger UI":"已加载资源信息。正在渲染Swagger UI", "Unable to read api":"没法读取api", "from path":"从路径", "server returned":"服务器返回" }); ===========接下来，正式进入Swagger2的使用教程===========

SpringBoot + Swagger2 使用教程

1. 引入依赖

org.springframework.boot spring-boot-starter-web io.springfox springfox-swagger2 2.7.0 io.springfox springfox-swagger-ui 2.7.0 org.springframework.boot spring-boot-devtools org.springframework.boot spring-boot-starter-test test 2. 添加配置 @Configuration //标记配置类 @EnableSwagger2 //开启在线接口文档 public class Swagger2Config { /** * 添加摘要信息(Docket) */ @Bean public Docket controllerApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(new ApiInfoBuilder() .title("标题：某公司_用户信息管理系统_接口文档") .description("描述：用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...") .contact(new Contact("一只袜子", null, null)) .version("版本号:1.0") .build()) .select() .apis(RequestHandlerSelectors.basePackage("com.hehe.controller")) .paths(PathSelectors.any()) .build(); } } 3. 编写接口文档 Swagger2 基本使用：

@Api 描述类/接口的主要用途 @ApiOperation 描述方法用途 @ApiImplicitParam 描述方法的参数 @ApiImplicitParams 描述方法的参数(Multi-Params) @ApiIgnore 忽略某类/方法/参数的文档 Swagger2 使用注解来编写文档：

Swagger2编写接口文档至关简单，只须要在控制层（Controller）添加注解来描述接口信息便可。例如：

package com.hehe.controller;

@Api("用户信息管理")

@RestController

@RequestMapping("/user/*")

public class UserController {

private final static List userList = new ArrayList<>();

{

userList.add(new User("1", "admin", "123456"));

userList.add(new User("2", "jacks", "111111"));

}

@ApiOperation("获取列表")

@GetMapping("list")

public List userList() {

return userList;

}

@ApiOperation("新增用户")

@PostMapping("save")

public boolean save(User user) {

return userList.add(user);

}

@ApiOperation("更新用户")

@ApiImplicitParam(name = "user", value = "单个用户信息", dataType = "User")

@PutMapping("update")

public boolean update(User user) {

return userList.remove(user) && userList.add(user);

}

@ApiOperation("批量删除")

@ApiImplicitParam(name = "users", value = "N个用户信息", dataType = "List")

@DeleteMapping("delete")

public boolean delete(@RequestBody List users) {

return userList.removeAll(users);

}

}

package com.hehe.entity;

public class User {

private String userId;

private String username;

private String password;

public User() {

}

public User(String userId, String username, String password) {

this.userId = userId;

this.username = username;

this.password = password;

}

@Override

public boolean equals(Object o) {

if (this == o) {

return true;

}

if (o == null || getClass() != o.getClass()) {

return false;

}

User user = (User) o;

return userId != null ? userId.equals(user.userId) : user.userId == null;

}

@Override

public int hashCode() {

int result = userId != null ? userId.hashCode() : 0;

result = 31 * result + (username != null ? username.hashCode() : 0);

result = 31 * result + (password != null ? password.hashCode() : 0);

return result;

}

public String getUserId() {

return userId;

}

public void setUserId(String userId) {

this.userId = userId;

}

public String getUsername() {

return username;

}

public void setUsername(String username) {

this.username = username;

}

public String getPassword() {

return password;

}

public void setPassword(String password) {

this.password = password;

}

}

4. 查阅接口文档 编写文档完成以后，启动当前项目，在浏览器打开：

[ http://localhost:8080/swagger-ui.html ] , 看到效果以下：

来看看save 方法的具体描述，能够看到Swagger 2.7.0 版本对参数列表进行了改版，直接输入参数，更方便进行测试操做：

5. 测试接口 Swagger2的强大之处不只在于快速生成整洁优雅的RestAPI文档，同时支持接口方法的测试操做（相似于客户端PostMan）。

以查询用户列表为例，无参数输入，直接点击“试一下”按钮：

而后能够看到以JSON格式返回的用户列表信息，很方便有木有：

喜欢的点点关注，点点赞。 对Java技术，架构技术感兴趣的同窗，欢迎加QQ群668041364?，一块儿学习，相互讨论。

群内已经有小伙伴将知识体系整理好（源码，笔记，PPT，学习视频），欢迎加群领取。