使用swwager生成离线API文档

概述

本文主要介绍如何使用swagger生成离线API。

项目架构

spring-boot-2.0 + swagger-2.8.0 .

需要哪些要素

3个配置文件

1. 静态文件StaticResourceFile，将静态文件中的文件夹放到/src目录下。
2. pom.xml 文件增加文档生成配置。
3. 增加JUNIT测试类，用于在使用mvn test命令时生成swagger.json文件，和生成配置文件。

如何使用

1. 将静态文件中的文件夹放到/src目录下。
2. 增加pom.xml 配置和文档路径配置。
3. 增加Swagger2MarkupTest.java到test目录，并且Swagger2MarkupTest.java包名称和项目启动类包名称保持一致。
4. 运行run maven test命令即可。

文件目录结构如下

这是项目结构，其中src中三个目录还有，测试类是必须的。

实现原理

使用MOCK调用接口，生成swagger.json以及swagger的其他参数，再通过swagger.json转化为接口文档

1. 先利用SpringFox库生成RESTful API
2. 再利用Swagger2Markup Maven插件生成asciidoc文档
3. 最后利用asciidoctor Maven插件生成 html 或 pdf 文件

资源文件地址

https://pan.baidu.com/s/14KC3v92_jHjQpaGfyokXYA
提取码：2xay

便利

github上有一些项目基于swagger2.6以上做了文档自动生成，只需要生成文档目标项目swaggerapi接口地址即可生成相关接口文档。
项目名swagger2pdf

备注

上面说明可以生成单个项目所需的离线文档，不是很方便，不建议将要生成文档的项目源码整合到本项目，这样做比较麻烦，需要每个项目都加。
比较好的做法是，新增一个项目用来单独生成swagger离线文档。

• 首先你的项目要确保是spring boot的，并且集成了swagger，接口层和入参出参实体类加了swagger的相关注解，且能正确跑起来；
• 然后将本项目的src/test/java下com.example.swagger2pdf中的Swagger2PdfTest类中的注释放开，将生成当前项目的swagger.json的代码注释掉。
• 将url中的ip和port换成自己要生成文档的项目的ip和port，这里要确保这个url直接访问有数据返回，不然是无法生成文档的；
• 最后按上面说的运行项目即可生成文档。

总结

swagger2.6.1版本之后的生成规则有些不一样，暂时没去研究。