pring Boot 开发者必备的 Swagger

pring Boot 开发者必备的 Swagger 集成技巧

wagger 最初作为一套规范而问世，后来在 2015 年捐赠给Linux基金会后演变为 OpenAPI 规范（OAS）。这次转变标志着 API 文档编写和互操作性的一次进步，使其向 OpenAPI 3.0 过渡。在现今的行业讨论中，提到 Swagger 通常指的是 SmartBear Software 开发的一套用于实现 OpenAPI 规范的工具。这套工具包括开源、免费和商业工具的组合，支持 API 生命周期的各个开发阶段。

什么是 Swagger？- 全面介绍Swagger 的作用和优点

使用 Swagger 工具的核心在于采用设计优先的原则，把生成 API 文档视为开发过程的基石。开发者可以根据自己的偏好选择方法：一些人偏好使用 Swagger Editor 在线创建 API 文档，而另一些人则偏好编写代码时注释，让文档自动生成。这两种方法都为简化和优化开发过程提供了路径。

如何使用 Swagger Editor 编写 API 文档

其中，Spring Boot 项目的集成已表现出良好的适应性，Springfox和Springdoc作为领先的开源库促进了这一整合。

Springfox与Springdoc深入探讨

Springfox：借鉴传统

Springfox 作为 Swagger 的 Java 实现，帮助生成兼容 Swagger 2.0 规范的 API 文档。它通过一系列注解为开发者提供了生成相应 API 文档的能力。此外，Springfox 还提供了可扩展接口，允许定制文档生成过程以满足特殊需求。尽管它因支持 Swagger 2 规范而被广泛使用，但更新速度缓慢和与新版本 Spring Boot 的兼容问题一直是人们关心的问题。

Springdoc：新兴前沿

与此同时，Springdoc 因其与 Spring Boot 的深度集成以及支持 OpenAPI 3.0 规范而脱颖而出。它涵盖了更广泛的Spring项目，包括 Spring WebMvc、Spring WebFlux、Spring Data Rest 和 Spring Security。以快速更新和生成 OpenAPI 3.0 规范文档而闻名，Springdoc 也为用户提供了自定义文档生成过程的能力，尽管目前支持的插件较少。

使用Springdoc-openapi发展文档

springdoc-openapi Java 库为 Spring Boot 应用中自动化生成 API 文档提供了创新解决方案。它通过审查应用的 Spring 配置、类结构和注释来推断 API 语义，产生格式化的 JSON/YAML 和 HTML 文档。

快速开始 Springdoc

安装依赖: 确认在项目的 POM 文件中加入最新版的springdoc-openapi-ui依赖。
启用Swagger: 在application.yml文件中修改配置以根据需要启用或禁用 Swagger 3。
配置SwaggerController: 实现一个 Swagger3Config 类来配置 API 分组，并为操作添加自定义参数或头部。
注释实体类: 对你的实体类使用 Swagger 的@Schema注释，以便准确地进行文档编写。
控制器注释: 通过为控制器方法添加 Swagger 的@Operation和@Parameter注释来精确定义 API。

访问 Swagger UI

通过访问http://server:port/context-path/swagger-ui.html来查看生成的 Swagger 文档。

其他方式

虽然springdoc-openapi为 API 文档提供了无与伦比的支持，但将其与 Apifox 整合为分享和同步 API 细节提供了一个吸引人的途径。Apifox 提供了一个全面的平台，支持 API 设计、文档、测试和协作功能，能够自动解析代码注释并从 Javadoc、KDoc 和 ScalaDoc 生成 API 文档。通过使用 IntelliJ IDEA 的 Apifox Helper 插件，开发人员可以在不离开 IDE 的情况下与 Apifox 项目同步他们的文档。此外，Apifox 通过其直观的UI丰富了 API 管理体验，支持从 IDEA 直接启动内部测试和导出文档。

如何使用 Apifox 自动生成 API 接口文档 - 一份详细指南

对于希望提升 API 文档和协作工作流的开发人员，采用 Apifox 与 Springdoc-openapi 可能成为改变游戏规则的策略。

、前言

Spring Boot作为当前最为流行的Java web开发脚手架，越来越多的开发者选择用其来构建企业级的RESTFul API接口。这些接口不但会服务于传统的web端（b/s），也会服务于移动端。在实际开发过程中，这些接口还要提供给开发测试进行相关的白盒测试，那么势必存在如何在多人协作中共享和及时更新API开发接口文档的问题。

使用 Swagger 集成文档具有以下几个优势：

功能丰富：支持多种注解，自动生成接口文档界面，支持在界面测试API接口功能；
及时更新：开发过程中花一点写注释的时间，就可以及时的更新API文档，省心省力；
整合简单：通过添加pom依赖和简单配置，内嵌于应用中就可同时发布API接口文档界面，不需要部署独立服务。

接下来，我们通过Spring Boot来整合Swagger实现在线API文档的功能，本文用的是SpringFox Swagger2，版本2.9.2（最新版本是3.0.0，但是在我测试是swagger-ui.html页面一直出不来，在https://mvnrepository.com/上也可以看到，2.9.2是目前使用最多的版本）

二、创建Spring Boot工程

我用的开发工具是IDEA，通过IDEA快速创建一个Spring Boot工程，创建时，只需勾选web依赖选项就成，不勾选也没关系，后面在pom.xml中配置也是一样的。注意创建工程时，工程名称都要是小写。

添加Swagger的两个依赖

<!-- swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

三、添加配置类

添加一个swagger 配置类，在工程下新建 config 包并添加一个 SwaggerConfig 配置类SwaggerConfig.java。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("在线API文档")
                .description("This is a restful api document of demo")
                .version("1.0")
                .build();
    }

}

以上就已经完成了Swagger的配置，是不是很简洁轻松。

四、创建一个测试Controller来验证配置

添加一个控制器，在工程下新建 controller包并添加一个 HelloController控制器HelloController.java。

package com.louis.springboot.demo.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;

/* 类注解 */
@Api
@RestController
public class HelloController {

    /* 方法注解 */
    @ApiOperation(value="desc of method", notes="")
    @GetMapping(value="/hello")
    public Object hello( @ApiParam(value="desc of param" , required=true ) @RequestParam String name) {
        return "Hello " + name + "!";
    }
}

五、编译运行测试

启动工程，打开浏览器，访问：http://localhost:8080/swagger-ui.html，进入swagger接口文档界面。

完毕收工，这样管理API接口很方便，并且是和代码实时更新的，不用烦心再去写接口文档啦。

附录：Swagger常用注解

API	使用位置
@Api	用于controller类上，表示标识这个类是swagger的资源
@ApiOperation	用在controller的方法上，表示一个http请求的操作
@ApiParam	方法中的参数注释
@ApiResponses	用在controller的方法上
@ApiResponse	用在 @ApiResponses里边
@ApiImplicitParams	用在controller的方法上
@ApiImplicitParam	用在@ApiImplicitParams的方法里边
@ApiModel	用在返回对象类上

WEB项目开发中碰到的问题千奇百怪。

者：yizhiwazi
链接：https://www.jianshu.com/p/7e543f0f0bd8

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

SpringBoot + Swagger2 UI界面-汉化教程

1.默认的英文界面UI

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

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

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

2.定制中文界面

2.1 添加首页和译文

重点来了，在src/main/resources目录下创建META-INF\resources目录，然后创建一个名称为"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在项目中的使用教程就到这里。

在线咨询

上一篇：作为动词的shanghai：美国加州的一段黑历史
下一篇：CSS图片浏览效果

您的项目需求

*请认真填写需求信息，我们会在24小时内与您取得联系。

整合营销服务商