Swagger2Markup导出AscIIDoc接口说明文档

最新推荐文章于 2025-11-15 07:40:14 发布

原创

最新推荐文章于 2025-11-15 07:40:14 发布 · 1k 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#swagger #生成文档

本文档介绍了如何使用Swagger2Markup工具将Swagger自动生成的接口文档转换为AsciiDoc格式，便于静态部署和使用。首先，文章讨论了Swagger作为API管理框架的重要性，然后讲解了Springfox在SpringBoot项目中的集成。接着，详细阐述了Swagger相关注解的用途，如@Api、@ApiOperation等。最后，展示了如何通过Swagger2Markup将API文档转换为AsciiDoc，并生成HTML静态文档的过程。

Swagger2Markup导出AscIIDoc接口说明文档

- 背景

背景

文档是每一个开发人员的痛点，自己开发的时候不想写文档，看别人代码的时候希望别人写文档。而原来大家都是通过手写文档来完成这个工作，缺点如下：
• 前后端联调接口，需要不断的更新接口文档，一般是文档跟不上接口变化的节奏；
• 接口返回结果不明确；
• 不能直接在线测试接口，通常需要使用工具，比如postman、jmeter；
• 接口文档太多，不好管理；
为了解决这个问题，引入API文档导出框架Swagger2Markup。在使用Swagger2Markup之前，首先要了解什么是Swagger

Swagger

swagger是一个API框架，号称世界上最流行的API工具。它提供了API管理的全套解决方案，比如API在线编辑器，APIUI展示界面，代码生成器等诸多功能。
Swagger官方地址

Springfox简介

如果想引入swagger进行API管理。目前springfox是一个很好的选择，它内部会自动解析Spring容器中Controller暴露出的接口，并且也提供了一个界面用于展示或调用这些API。
Springbox官方地址
下面介绍一个Springboot项目如何集成Swagger
1.导入Maven依赖
在这里插入图片描述
2.创建Swagger配置类

3. Application.class 加上注解@EnableSwagger2 表示开启Swagger

4. REST API接口增加Swagger注释

5.其他按照正常SpringBoot项目配置即可。
6.启动项目，打开url

最低0.47元/天解锁文章