logo资料库

使用swagger2markup和asciidoctor生成美观的Restful API文档.docx

发布时间：2022-05-29 发布人：admin 分类：说明书 资料大小：0.46M 资料格式：docx 举报 版权申诉
第1页 / 共18页
第2页 / 共18页
第3页 / 共18页
第4页 / 共18页
第5页 / 共18页
第6页 / 共18页
第7页 / 共18页
第8页 / 共18页
资料共18页，剩余部分请下载后查看
    使用swagger2markup和asciidoctor生成美观的Restful API文档
    参考文献
    使用 swagger2markup 和 asciidoctor 生成美观的 Restful API 文档 目前，大家通常都是用 Swagger 来编写 Rest API 文档，使用 Swagger 注解和 Springfox，可 以方便的从源代码生成文档，保持文档和源码一致。使用 Swagger-ui 工具，接口的消费方 可以查看接口定义并从浏览器直接调用接口。如何实现 Swagger 和 Spring Boot 项目的结合， 可以参考文章 Spring Boot RESTful API Documentation With Swagger 2 和 Springfox 的官方 文档。 但是，有时我们为其它读者提供 API 文档，例如尊贵的客户领导要验收工作成果，Swagger UI 就显得不太正式了，而且要连接上运行 Swagger UI 的服务器才可以完整的查看。最近， 笔者找到了工具 swagger2markup 和 asciidoctor，结合起来使用就可以输出优美的 API 文档 了，供大家参考。 使用 Swagger2Markup Demo 笔者尝试了多种方式后，发现结合 swagger2markup 和 asciidoctor 两个工具需要较多的 配置，Swagger2Markup Demo 项目已经做好了基本的配置，是一个 Quick-Wins 的路径。 样例程序的使用 从 GitHub 上克隆 Swagger2Markup Demo 项目，然后导入 idea。
    如上图所示，在项目中，swagger2markup 和 asciidoctor 是在 pom.xml 文件中以 Maven 插 件的形式引入的，项目已经对两个插件做了配置。在 src/docs/asciidoc 目录中，存放了生成 最终文档的索引文件，index.adoc 的内容是： include::{generated}/overview.adoc[] include::{generated}/paths.adoc[] include::{generated}/definitions.adoc[] {generated}目录下的 adoc 文件都是 swagger2markup 根据 swagger 生成的，同时，该 文件示例引入了两个静态文件 manual_content1.adoc 和 manual_content2.adoc(本人未发现 这两个文件。 在项目上执行 mvn clean test，执行成功后，即可在 target/asciidoc/html 目录下找到生成 的 index.html 文档，如下所示，是否觉得可读性比 Swagger UI 好多了？
    还可以在 target\asciidoc\pdf 目录中可以找到生成的 index.pdf 文档，不过当 REST API 文档 中有中文时，生成的 PDF 会发生漏字的问题，无法使用。 样例程序的原理是 springfox-staticdocs 从 API 代码的注解生成了静态的 Swagger API 文 档 swagger.json ， 并 放 在 了 target/swagger 目 录 下 。 swagger2markup 读 取 静 态 的 swagger.json 文件生成了 asciidoctor 所需的 adoc 文件。下面一起来看看如何使用动态的 Swagger API 文档。 使用动态 Swagger API 文档 假设项目的动态 Swagger 地址是 http://localhost:6060/v2/api-docs，注意在浏览器中打 开应当看到一个 JSON 文档，而非 Swagger UI。如图，将 spring-swagger2markup-demo 项目 pom.xml 文件中的 swaggerInput 标签中的内容改为动态 Swagger 的地址。
    再次执行 mvn clean test，即可在 target/asciidoc/html 目录下找到新生成的 index.html 文档。 生成请求和响应的样例 JSON Swagger UI 中有一个很棒的特性，就是可以显示请求和响应的样例 JSON，便于接口的 消费方使用。但在样例中，生成的文档中并没有样例 JSON，可以通过在 swagger2markup Maven 插件中增加一项 swagger2markup.generatedExamplesEnabled 配置来增加样例 JSON， 如图： 再次执行 mvn clean test，即可在 target/asciidoc/html 目录下找到新生成的 index.html 文档。可以看到生成的 JSON 样例：
    在文档中添加静态章节 前文中已经介绍了，样例中演示了如何在 index.adoc 中引入静态章节，我们可以利用这 一 特 性 添 加 一 些 Swagger 没 有 生 成 的 内 容 ， 作 为 API 文 档 的 补 充 ， 如 笔 者 在 manual_content1.adoc 中定义了一段码表内容： == 码表 === 性别 [options="header", cols=".^2,.^14"] |=== |代码|含义 |**M**|男 |**F**|女 |=== 执行 mvn clean test 后，在文档中添加了以下的内容：
    参考文献 https://blog.csdn.net/gongxsh00/article/details/80508963 https://blog.csdn.net/lihuaijun/article/details/79727863 使用 Swagger2Markup、asciidoctor-maven-plugin 和 asciidoctorj-pdf 插件能生成 pdf 格式 的文档，但是对于中文支持太差了，很多中文字符是空白。 需要替换 jar: asciidoctorj-pdf-1.5.0-alpha.16 Jar 包下载地址: https://download.csdn.net/download/lihuaijun/10313631 以下是 pom.xml 文件配置
    com.***.icore ***-abc 1.0.0 4.0.0 127.0.0.1:8888 1.3.3 1.3.3 ${project.basedir}/src/docs/asciidoc
    ${project.build.directory}/swagger ${project.build.directory}/asciidoc/snippets ${project.basedir}/src/docs/asciidoc/generated ${project.build.directory}/asciidoc/html ${project.build.directory}/asciidoc/pdf
    分享到：
    赞 收藏

    相关推荐

    资料库

    开发技术

    共收录19306份资料，累计14个分类，关注成员有19位，主要包括：Actionscript,Javascript,PHP,VB,Perl,Delphi,Python,C#,C,Java,C++,Web开发,硬件开发,其它

    热门标签

    Actionscript Javascript PHP VB Perl Delphi Python C# C Java C++ Web开发 硬件开发 其它

    最新资料