原文地址: https://www.jianshu.com/p/7e543f0f0bd8

SpringBoot + Swagger2 UI界面-汉化教程

1.默认的英文界面UI

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

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

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

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

2.定制中文界面

2.1 添加首页和译文

重点来了，在resoureces目录下创建\META-INF\resoureces目录，然后创建一个名称为"swagger-ui.html" 的HTML文件。如图：

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

<!DOCTYPE html>

<html>

<head>

    <meta charset="UTF-8">

    <title>Swagger UI</title>

    <link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-32x32.png" sizes="32x32"/>

    <link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-16x16.png" sizes="16x16"/>

    <link href='webjars/springfox-swagger-ui/css/typography.css' media='screen' rel='stylesheet' type='text/css'/>

    <link href='webjars/springfox-swagger-ui/css/reset.css' media='screen' rel='stylesheet' type='text/css'/>

    <link href='webjars/springfox-swagger-ui/css/screen.css' media='screen' rel='stylesheet' type='text/css'/>

    <link href='webjars/springfox-swagger-ui/css/reset.css' media='print' rel='stylesheet' type='text/css'/>

    <link href='webjars/springfox-swagger-ui/css/print.css' media='print' rel='stylesheet' type='text/css'/>

    <script src='webjars/springfox-swagger-ui/lib/object-assign-pollyfill.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/lib/jquery-1.8.0.min.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/lib/jquery.slideto.min.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/lib/jquery.wiggle.min.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/lib/jquery.ba-bbq.min.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/lib/handlebars-4.0.5.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/lib/lodash.min.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/lib/backbone-min.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/swagger-ui.min.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack_extended.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/lib/jsoneditor.min.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/lib/marked.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/lib/swagger-oauth.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/springfox.js' type='text/javascript'></script>

    <!--国际化操作：选择中文版 -->

    <script src='webjars/springfox-swagger-ui/lang/translator.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/lang/zh-cn.js' type='text/javascript'></script>

</head>

<body class="swagger-section">

<div id='header'>

    <div class="swagger-ui-wrap">

        <a id="logo" href="http://swagger.io">![](webjars/springfox-swagger-ui/images/logo_small.png)<span class="logo__title">swagger</span></a>

        <form id='api_selector'>

            <div class='input'>

                <select id="select_baseUrl" name="select_baseUrl"></select>

            </div>

            <div class='input'><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text"/></div>

            <div id='auth_container'></div>

            <div class='input'><a id="explore" class="header__btn" href="#" data-sw-translate>Explore</a></div>

        </form>

    </div>

</div>

<div id="message-bar" class="swagger-ui-wrap" data-sw-translate> </div>

<div id="swagger-ui-container" class="swagger-ui-wrap"></div>

</body>

</html>

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. 引入依赖

    <!--依赖管理 -->

    <dependencies>

        <dependency> <!--添加Web依赖 -->

            <groupId>org.springframework.boot</groupId>

            <artifactId>spring-boot-starter-web</artifactId>

        </dependency>

        <dependency><!--添加Swagger依赖 -->

            <groupId>io.springfox</groupId>

            <artifactId>springfox-swagger2</artifactId>

            <version>2.7.0</version>

        </dependency>

        <dependency><!--添加Swagger-UI依赖 -->

            <groupId>io.springfox</groupId>

            <artifactId>springfox-swagger-ui</artifactId>

            <version>2.7.0</version>

        </dependency>

        <dependency> <!--添加热部署依赖 -->

            <groupId>org.springframework.boot</groupId>

            <artifactId>spring-boot-devtools</artifactId>

        </dependency>

        <dependency><!--添加Test依赖 -->

            <groupId>org.springframework.boot</groupId>

            <artifactId>spring-boot-starter-test</artifactId>

            <scope>test</scope>

        </dependency>

    </dependencies>

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<User> 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<User>")

    @DeleteMapping("delete")

    public boolean delete(@RequestBody List<User> 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格式返回的用户列表信息，很方便有木有：

好了，关于Swagger2在项目中的使用教程就到这里。

源码下载： SpringBoot +Swagger2 使用教程

专题阅读：《SpringBoot 布道系列》

作者：yizhiwazi
链接：https://www.jianshu.com/p/7e543f0f0bd8
來源：简书
简书著作权归作者所有，任何形式的转载都请联系作者获得授权并注明出处。

SpringBoot 使用Swagger2打造在线接口文档（附汉化教程）的更多相关文章

spring boot 2.x 系列——spring-boot 集成 Swagger2 打造在线接口文档
文章目录一.Springfox 与 Swagger 简介 1.1 Springfox 1.2 Swagger 1.3 OpenApi.Swagger.Springfox的关系二.spring bo ...
第05章—Swagger2打造在线接口文档
spring boot 系列学习记录:http://www.cnblogs.com/jinxiaohang/p/8111057.html 码云源码地址:https://gitee.com/jinxia ...
springboot项目利用Swagger2生成在线接口文档
Swagger简介. Swagger2是一款restful接口文档在线生成和在线调试工具.很多项目团队利用Swagger自动生成接口文档,保证接口文档和代码同步更新.在线调试.简单地说,你可以利用这个 ...
使用swagger实现web api在线接口文档
一.前言通常我们的项目会包含许多对外的接口,这些接口都需要文档化,标准的接口描述文档需要描述接口的地址.参数.返回值.备注等等:像我们以前的做法是写在word/excel,通常是按模块划分,例如一个 ...
.NET Core WEB API使用Swagger生成在线接口文档
1项目引用Swashbuckle.AspNetCore程序集和Microsoft.Extensions.PlatformAbstractions程序集右击项目打开"管理NuGet程序包.. ...
使用swagger实现web api在线接口文档（转载）
一.前言通常我们的项目会包含许多对外的接口,这些接口都需要文档化,标准的接口描述文档需要描述接口的地址.参数.返回值.备注等等:像我们以前的做法是写在word/excel,通常是按模块划分,例如一个 ...
ubuntu下vim及man帮助文档的汉化
vim是一个功能超级强大的编辑器,当然我们也可将它配置超强的IDE.这类教程网上非常多,我就不再此赘述了. 我们在使用中对不熟悉的命令,不熟悉的插件的使用方法常常须要查看文档,全英文环境确实看着人头都 ...
Spring Boot（九）Swagger2自动生成接口文档和Mock模拟数据
一.简介在当下这个前后端分离的技术趋势下,前端工程师过度依赖后端工程师的接口和数据,给开发带来了两大问题: 问题一.后端接口查看难:要怎么调用?参数怎么传递?有几个参数?参数都代表什么含义? 问题二 ...
net core Webapi基础工程搭建（三）——在线接口文档Swagger
目录前言 Swagger NuGet引用第三方类库别急,还有没错,注释小结前言前后分离的好处,就是后端埋头做业务逻辑功能,不需要过多考虑用户体验,只专注于数据.性能开发,对于前端需要的数据 ...

随机推荐

007 @CookieValue绑定请求中的cookie
1.介绍 2.使用的cookie 3.index.jsp <%@ page language="java" contentType="text/html; char ...
MIT-6.824 Lab 3: Fault-tolerant Key/Value Service
概述 lab2中实现了raft协议,本lab将在raft之上实现一个可容错的k/v存储服务,第一部分是实现一个不带日志压缩的版本,第二部分是实现日志压缩.时间原因我只完成了第一部分. 设计思路如上图 ...
文件上传按钮input[type="file"]按钮美化时在IE8中的bug【兼容至IE8】
首先看一下完成后的效果,鼠标移入可改变为手指的效果. 在此就不加图标了 <label class="file-upload"> <span>上传附件< ...
InnoDB的锁机制浅析(一)—基本概念/兼容矩阵
InnoDB锁的基本概念文章总共分为五个部分: InnoDB的锁机制浅析(一)-基本概念/兼容矩阵 InnoDB的锁机制浅析(二)-探索InnoDB中的锁(Record锁/Gap锁/Next-key ...
Windows栈溢出原理
1.栈是什么? 栈是一种运算受限的线性表其限制是仅允许在表的一端进行插入和删除运算这一端称为栈顶(TOP),相对的另一端称为栈底(BASE) 向一个栈插入新元素,称作进栈.入栈或压栈(PUSH) ...
Meta对照表
Http Content_type对照表: 文件扩展名 Content-Type(Mime-Type) 文件扩展名 Content-Type(Mime-Type) .*( 二进制流,不知道下载文件类型 ...
使用 IntraWeb (26) - 基本控件之 TIWMenu
TIWMenu 的任务是让原来的 TMainMenu 呈现在网页上, 通过其 AttachedMenu 属性关联一个 TMainMenu 是必需的. TIWMenu 所在单元及继承链: IWCompM ...
spring cloud 学习(7) - 生产环境如何不停机热发布？
业务繁忙的系统,原则上是不允许停机的,那么问题来了,如果真有严重的bug要修复,不得不发布,怎么做到不停机发布,对业务无感知呢? eureka 提供了一系列rest url,可以对注册实例进行操作,比 ...
Spring 注解学习手札（七）补遗——@ResponseBody，@RequestBody，@PathVariable(转)
最近需要做些接口服务,服务协议定为JSON,为了整合在Spring中,一开始确实费了很大的劲,经朋友提醒才发现,SpringMVC已经强悍到如此地步,佩服! 相关参考: Spring 注解学习手札(一 ...
一个.net程序客户端更新方案
客户端程序一个很大的不便的地方就是程序集更新,本文这里简单的介绍一种通用的客户端更新方案.这个方案依赖程序集的动态加载,具体方案如下: 将程序集存储在一个文件数据库中,客户端所有程序集直接从文件数据库 ...

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