reset.css SpringBoot 使用Swagger2打造在线接口文档（附汉化教程）

链接：

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

SpringBoot + Swagger2 UI界面-汉化教程1.默认的英文界面UI

想必很多小伙伴都曾经使用过Swagger，但是打开UI界面之后，却是下面这样的画风，纯英文的界面并不太友好，作为国人还是习惯中文界面。

reset.css_reset.css下载_cssreset样式

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

reset.css下载_cssreset样式_reset.css

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

cssreset样式_reset.css_reset.css下载

2.定制中文界面2.1 添加首页和译文

重点来了，在src/main/resources目录下创建META-INFresources目录，然后创建一个名称为”swagger-ui.html” 的HTML文件。如图：

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



 
 Swagger UI
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 



 
 ![](webjars/springfox-swagger-ui/images/logo_small.png)swagger
 
 
 
 
 
 
 Explore

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

reset.css_cssreset样式_reset.css下载

reset.css下载_cssreset样式_reset.css

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

2.2 更详细的译文翻译（非必需）

如果想进一步调整译文，可以在META-INFresourceswebjarsspringfox-swagger-uilang 目录下添加zh-cn.js文件.

reset.css下载_reset.css_cssreset样式

然后在译文（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 基本使用：

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. 查阅接口文档

编写文档完成之后，启动当前项目，在浏览器打开：

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

cssreset样式_reset.css下载_reset.css