Spring Boot 2.X集成 Swagger2 开发 API 文档（在线+离线）
发布日期：2021-05-06 22:27:12
浏览次数：22
分类：技术文章
本文共 14003 字，大约阅读时间需要 46 分钟。
点击上方蓝色字体，选择“标星公众号”
优质文章，第一时间送达
上一篇：
下一篇：
作者：朝雾轻寒 来源：开源中国：
http://suo.im/6iDzqd
前言
相信很多后端开发在项目中都会碰到要写 api 文档，不管是给前端、移动端等提供更好的对接，还是以后为了以后交接方便，都会要求写 api 文档。
而手写 api 文档的话有诸多痛点：
文档更新的时候，需要再次发送给对接人
接口太对，手写文档很难管理
接口返回的结果不明确
不能直接在线测试接口，通常需要使用工具，如 postman 等
Swagger 就很好的解决了这个问题。
Swagger 简介
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。
官网：https://swagger.io
Swagger 使用
1.相关依赖
io.springfox springfox-swagger2 2.9.2 io.springfox springfox-swagger-ui 2.9.2
2.Swagger 配置类
@Configuration@EnableSwagger2public class SwaggerConfig { @Bean public Docket buildDocket() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(buildApiInf()) //将api的元信息设置为包含在json resourcelisting响应中 //.host("127.0.0.1:8080") //设置ip和端口，或者域名 .select() //启动用于api选择的生成器 //.apis(RequestHandlerSelectors.any()) .apis(RequestHandlerSelectors.basePackage("cn.zwqh.springboot.controller"))//指定controller路径 .paths(PathSelectors.any()).build(); } private ApiInfo buildApiInf() { Contact contact=new Contact("朝雾轻寒","https://www.zwqh.top/","zwqh@clover1314.com"); return new ApiInfoBuilder() .title("Swagger Demo Restful API Docs")//文档标题 .description("Swagger 示例 Restful Api 文档")//文档描述 .contact(contact)//联系人 .version("1.0")//版本号 //.license("")//更新此API的许可证信息 //.licenseUrl("")//更新此API的许可证Url //.termsOfServiceUrl("")//更新服务条款URL .build(); }} 3.Spring MVC 相关配置
@Configurationpublic class WebMvcConfig extends WebMvcConfigurationSupport { /** * 静态资源配置(默认) */ @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");// 静态资源路径 registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/"); super.addResourceHandlers(registry); }} 如果不添加此静态资源配置会报错，找不到相关路径
4.Model 中使用 Swagger 注解
@ApiModel(value = "UserEntity", description = "用户对象")public class UserEntity implements Serializable{ /** * */ private static final long serialVersionUID = 5237730257103305078L; @ApiModelProperty(value ="用户id",name="id",dataType="Long",required = false,example = "1",hidden = false ) private Long id; @ApiModelProperty(value ="用户名",name="userName",dataType="String",required = false,example = "关羽" ) private String userName; @ApiModelProperty(value ="用户性别",name="userSex",dataType="String",required = false,example = "男" ) private String userSex; public Long getId() { return id; } public void setId(Long id) { this.id = id; } public String getUserName() { return userName; } public void setUserName(String userName) { this.userName = userName; } public String getUserSex() { return userSex; } public void setUserSex(String userSex) { this.userSex = userSex; }} 5. Controller 中使用 Swagger 注解
@RestController@RequestMapping("/api")@Api(tags = { "接口分组1", "接口分组2" })public class ApiController { @Autowired private UserDao userDao; @GetMapping("/getAllUser") @ApiOperation(value = "获取所有用户", notes = "", httpMethod = "GET", tags = "接口分组3") public List getAll() { return userDao.getAll(); } @GetMapping("/getUserById") @ApiOperation(value = "根据id获取用户", notes = "id必传", httpMethod = "GET") @ApiImplicitParam(name = "id", value = "用户id",example = "1", required = true, dataType = "long", paramType = "query") public UserEntity getOne(Long id) { return userDao.getOne(id); } @PostMapping("/getUserByNameAndSex") @ApiOperation(value = "根据name和sex获取用户", notes = "", httpMethod = "POST") @ApiImplicitParams({ @ApiImplicitParam(name = "userName", value = "用户名", example = "关羽", required = true, dataType = "string", paramType = "query"), @ApiImplicitParam(name = "userSex", value = "用户性别", example = "男", required = true, dataType = "string", paramType = "query") }) public UserEntity getUserByNameAndSex(String userName, String userSex) { return userDao.getUserByNameAndSex(userName, userSex); } @PostMapping("/insertUser") @ApiOperation(value = "新增用户", notes = "传json，数据放body", httpMethod = "POST") @ApiImplicitParams({ @ApiImplicitParam(name = "body", value = "用户对象json", example = "{userName:'朝雾轻寒',userSex:'男'}", required = true) }) public String insertUser(@RequestBody String body) { System.out.println(body); UserEntity user = JSON.parseObject(body, UserEntity.class); userDao.insertUser(user); return "{code:0,msg:'success'}"; } @PostMapping("/updateUser") @ApiOperation(value = "修改用户", notes = "传json，数据放body", httpMethod = "POST") @ApiImplicitParams({ @ApiImplicitParam(name = "body", value = "用户对象json", example = "{id:23,userName:'朝雾轻寒',userSex:'女'}", required = true) }) public String updateUser(@RequestBody String body) { System.out.println(body); UserEntity user = JSON.parseObject(body, UserEntity.class); userDao.updateUser(user); return "{code:0,msg:'success'}"; } @PostMapping("/deleteUser") @ApiOperation(value = "删除用户", notes = "id必传", httpMethod = "POST") public String deleteUser(@ApiParam(name = "id", value = "用户id", required = true) Long id) { userDao.deleteUser(id); return "{code:0,msg:'success'}"; }} 6.测试
访问 http://127.0.0.1:8080/swagger-ui.html 进行接口在线测试
Swagger 常用注解
1.@Api
用于类，表示标识这个类是swagger的资源。属性如下：
tags 表示说明，tags如果有多个值，会生成多个列表
value 表示说明，可以使用tags替代
2.@ApiOperation
用于方法，表示一个http请求的操作。属性如下：
value 用于方法描述
notes 用于提示内容
tags 用于API文档控制的标记列表，视情况而用，可以进行独立分组
3.@ApiParam
用于方法、参数、字段说明；表示对参数的添加元数据。
name 参数名
value 参数说明
required 是否必填
4.@ApiModel
用于类，表示对类进行说明，用于参数用实体类接受。
value 对象名
description 描述
5.@ApiModelProperty
用于方法、字段，表示对model属性的说明或者数据操作更改。
value 字段说明
name 重写属性名
dataType 重写属性数据类型
required 是否必填
example 举例说明
hidden 隐藏
6.@ApiIgnore
用于类、方法、方法参数，表示这个方法或者类被忽略，不在swagger-ui.html上显示。
7.@ApiImplicitParam
用于方法，表示单独的请求参数。
name 参数名
value 参数说明
dataType 数据类型
paramType 参数类型
example 举例说明
8.@ApiImplicitParams
用于方法，包含多个 @ApiImplicitParam。
9.@ApiResponses @ApiResponse
用于类或者方法，描述操作的可能响应。
code 响应的HTTP状态代码
message 响应附带的可读消息
10.@ResponseHeader
用于方法，响应头设置。
name 响应头名称
description 头描述
response 默认响应类 void
responseContainer 参考ApiOperation中配置
Swagger 导出离线 api 文档
1.导出 AsciiDocs、Markdown、Confluence 格式文档
添加依赖
io.github.swagger2markup swagger2markup 1.3.3
转换工具类
public class SwaggerUtils { private static final String url = "http://127.0.0.1:8080/v2/api-docs"; /** * 生成AsciiDocs格式文档 * @throws MalformedURLException */ public static void generateAsciiDocs() throws MalformedURLException { Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.ASCIIDOC) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema().build(); Swagger2MarkupConverter.from(new URL(url)) .withConfig(config) .build() .toFolder(Paths.get("./docs/asciidoc/generated")); } /** * 生成AsciiDocs格式文档,并汇总成一个文件 * @throws MalformedURLException */ public static void generateAsciiDocsToFile() throws MalformedURLException { Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.ASCIIDOC) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL(url)) .withConfig(config) .build() .toFile(Paths.get("./docs/asciidoc/generated/all")); } /** * 生成Markdown格式文档 * @throws MalformedURLException */ public static void generateMarkdownDocs() throws MalformedURLException { Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.MARKDOWN) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL(url)) .withConfig(config) .build() .toFolder(Paths.get("./docs/markdown/generated")); } /** * 生成Markdown格式文档,并汇总成一个文件 * @throws MalformedURLException */ public static void generateMarkdownDocsToFile() throws MalformedURLException { Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.MARKDOWN) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL(url)) .withConfig(config) .build() .toFile(Paths.get("./docs/markdown/generated/all")); } /** * 生成Confluence格式文档 * @throws MalformedURLException */ public static void generateConfluenceDocs() throws MalformedURLException { Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL(url)) .withConfig(config) .build() .toFolder(Paths.get("./docs/confluence/generated")); } /** * 生成Confluence格式文档,并汇总成一个文件 * @throws MalformedURLException */ public static void generateConfluenceDocsToFile() throws MalformedURLException { Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL(url)) .withConfig(config) .build() .toFile(Paths.get("./docs/confluence/generated/all")); } } 使用测试 Controller
@RestController@RequestMapping("/export")@ApiIgnorepublic class ExportController { @RequestMapping("/ascii") public String exportAscii() throws MalformedURLException{ SwaggerUtils.generateAsciiDocs(); return "success"; } @RequestMapping("/asciiToFile") public String asciiToFile() throws MalformedURLException{ SwaggerUtils.generateAsciiDocsToFile(); return "success"; } @RequestMapping("/markdown") public String exportMarkdown() throws MalformedURLException{ SwaggerUtils.generateMarkdownDocs(); return "success"; } @RequestMapping("/markdownToFile") public String exportMarkdownToFile() throws MalformedURLException{ SwaggerUtils.generateMarkdownDocsToFile(); return "success"; } @RequestMapping("/confluence") public String confluence() throws MalformedURLException{ SwaggerUtils.generateConfluenceDocs(); return "success"; } @RequestMapping("/confluenceToFile") public String confluenceToFile() throws MalformedURLException{ SwaggerUtils.generateConfluenceDocsToFile(); return "success"; }} 2.导出 html、pdf、xml 格式
添加依赖
org.springframework.restdocs spring-restdocs-mockmvc test io.springfox springfox-staticdocs 2.6.1
org.springframework.boot spring-boot-maven-plugin io.github.swagger2markup swagger2markup-maven-plugin 1.3.1 http://127.0.0.1:8080/v2/api-docs ./docs/asciidoc/generated ASCIIDOC org.asciidoctor asciidoctor-maven-plugin 1.5.3 org.asciidoctor asciidoctorj-pdf 1.5.0-alpha.10.1 org.jruby jruby-complete 1.7.21 ./docs/asciidoc/generated ./docs/asciidoc/html html true book coderay left 3 true
可以修改此处 html 和 pdf，通过 mvn asciidoctor:process-asciidoc 可以导出相应格式文件
./docs/asciidoc/html html
执行 mvn asciidoctor:process-asciidoc 后再执行 mvn generate-resources，可在 targt/generated-docs 目录下生成 xml 格式文件。
完整代码
https://github.com/zwqh1992/Spring-Boot-2.X/tree/master/spring-boot-swagger2
说句题外话，springboot全家桶技术交流群可以加我微信，但是坑位有限哦，由于忙于工作，有时不能及时回复大家，请多包涵。
猜你喜欢1、Java : 对象不再使用时，为什么要赋值为 null ？2、一份不可多得的 Lombok 学习指南3、为什么说++i比i++效率高？4、ZooKeeper基本原理5、在 IntelliJ IDEA 中使用 Git，太方便了！6、Redis实战--使用Jedis实现百万数据秒级插入7、7 个显著提升编码效率的IntelliJ IDEA必备插件8、免费版的 IDEA 为啥不能使用 Tomcat ？强烈推荐一位大佬的公众号好文章，我在看❤️
发表评论
最新留言
能坚持，总会有不一样的收获！
[***.219.124.196]2025年03月27日 23时45分17秒
关于作者
喝酒易醉，品茶养心，人生如梦，品茶悟道，何以解忧？唯有杜康！
-- 愿君每日到此一游！
推荐文章
【树形dp】P1273 有线电视网
2019-03-03
【最短路】P4408 [NOI2003]逃学的小孩
2019-03-03
2020电工（初级）考试及电工（初级）考试软件
2019-03-03
2020N1叉车司机模拟考试题库及N1叉车司机复审模拟考试
2019-03-03
2020年制冷与空调设备运行操作答案解析及制冷与空调设备运行操作考试总结
2019-03-03
2020年保育员（初级）考试资料及保育员（初级）新版试题
2019-03-03
2020年茶艺师（高级）考试内容及茶艺师（高级）考试申请表
2019-03-03
2021年重氮化工艺考试题库及重氮化工艺考试报名
2019-03-03
2021年车工（高级）考试总结及车工（高级）试题及答案
2019-03-03
2021年压力焊证考试及压力焊实操考试视频
2019-03-03
2021年低压电工考试及低压电工考试申请表
2019-03-03
2021年低压电工考试及低压电工考试申请表
2019-03-03
2021年A特种设备相关管理（电梯）考试APP及A特种设备相关管理（电梯）复审考试
2019-03-03
2021年N1叉车司机考试题及N1叉车司机复审模拟考试
2019-03-03
2021年危险化学品经营单位主要负责人考试APP及危险化学品经营单位主要负责人多少钱
2019-03-03
2021年T电梯修理考试技巧及T电梯修理模拟考试软件
2019-03-03
2021年电工（初级）考试及电工（初级）证考试
2019-03-03
大数据学习之Spark——00Spark项目的pom.xml文件
2019-03-03
CodeBlocks开发wxWidgets环境配置详细
2019-03-03
白红宇的个人博客 - 记录点点滴滴的事 - 您是第 453533028 位访客
访问时间: 2025-04-08 10:04:30
访问IP: 18.221.240.145
Copyright © 2020 - 2025 css8.cn 京ICP备2021015314号-1
手机版