SpringBoot 使用Swagger2打造在线接口文档(附源代码)

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

SpringBoot + Swagger2 UI界面-汉化教程

1.默认的英文界面UI

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

image

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

image

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

image

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

重点来了,在src/main/resources目录下创建META-INF\resources目录,然后创建一个名称为"swagger-ui.html" 的HTML文件。如图:

image

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

<html>
<head>
    <meta charset="UTF-8">
    <title>Swagger UItitle>
    <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">swaggerspan>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>Explorea>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 看看显示效果:

image

image

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

2.2 更详细的译文翻译(非必需)

如果想进一步调整译文,可以在META-INF\resources\webjars\springfox-swagger-ui\lang 目录下添加zh-cn.js文件.

image

然后在译文(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":"服务器返回"
});

SpringBoot + Swagger2 使用教程

1、 引入依赖
    <dependencies>
        <dependency> 
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-starter-webartifactId>
        dependency>
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger2artifactId>
            <version>2.7.0version>
        dependency>
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger-uiartifactId>
            <version>2.7.0version>
        dependency>
        <dependency> 
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-devtoolsartifactId>
        dependency>
        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-starter-testartifactId>
            <scope>testscope>
        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 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 ] , 看到效果如下:

image

来看看save 方法的具体描述,可以看到Swagger 2.7.0 版本对参数列表进行了改版,直接输入参数,更方便进行测试操作:

image

5、测试接口

Swagger2的强大之处不仅在于快速生成整洁优雅的RestAPI文档,同时支持接口方法的测试操作(类似于客户端PostMan)。

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

image

然后可以看到以JSON格式返回的用户列表信息,很方便有木有:

image

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

  • 源码下载:https://github.com/yizhiwazi/springboot-socks/tree/master/springboot-swagger2
  • 专题阅读:https://www.jianshu.com/p/964370d9374e

原文发布于微信公众号 - 好好学java(SIHAIloveJAVA)

原文发表时间:2018-09-18

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏我和PYTHON有个约会

Django来敲门~第一部分【5.1.项目配置settings.py详解】

我们创建好了一个Python项目(mysite/)之后,需要在项目中添加模块应用(polls/),在模块应用中添加处理功能逻辑,如添加模块中的视图处理函数(po...

953
来自专栏Ryan Miao

Java Web基础入门

前言 语言都是相通的,只要搞清楚概念后就可以编写代码了。而概念是需要学习成本的。 Java基础 不用看《编程思想》,基础语法看 http://www.runo...

3437
来自专栏FreeBuf

安全科普:SQLi Labs 指南(Part 3)

Freebuf上有两篇SQLi Labs的教程安全科普:SQLi Labs 指南 Part 1和安全科普:SQLi Labs 指南 Part 2。这两篇教程只讲...

2079
来自专栏遊俠扎彪

如何在命令行中处理CSV文件

CSV,全称Comma-Separated Values。CSV文件是每一行都是以逗号分隔的纯文本文件。

3020
来自专栏MasiMaro 的技术博文

OLEDB数据源

OLEDB虽然是基于COM的一组接口,但是它与标准的COM接口有点不同,它的一大特色在于它自身的属性设置,有的接口虽然对象中存在但是调用QueryInterfa...

1282
来自专栏Java帮帮-微信公众号-技术文章全总结

Hibernate_day01总结

? 第1章 Hibernate_day01总结 今日内容 Hibernate框架的概述 Hibernate的快速入门 Hibernate核心API的介绍 Hi...

3409
来自专栏MasiMaro 的技术博文

PE文件解析器的编写(二)——PE文件头的解析

之前在学习PE文件格式的时候,是通过自己查看各个结构,自己一步步计算各个成员在结构中的偏移,然后在计算出其在文件中的偏移,从而找到各个结构的值,但是在使用C语言...

1192
来自专栏Java架构沉思录

你真的懂Mybatis缓存机制吗

Mybatis的一级缓存是指Session缓存。一级缓存的作用域默认是一个SqlSession。Mybatis默认开启一级缓存。 也就是在同一个SqlSessi...

1.3K5
来自专栏日常分享

JavaWeb 基于Session的用户登陆注销实现

  通过Session来存储用户的部分登陆信息来验证用户是否在线,这应该时最容易实现的一种Web端方案,本文以SSM(Spring、SpringMVC、myBa...

3771
来自专栏Felix的技术分享

《一个操作系统的实现》笔记(5)--内核雏形

1824

扫码关注云+社区