使用Swagger2Markup归档swagger生成的API文档

2022-12-05 17:45:19

文章出处： http://blog.didispace.com/swagger2markup-asciidoc/

说明

项目中使用Swagger之后，我们能够很轻松的管理API文档，并非常简单的模拟接口调用，但是构建的文档必须通过在项目中整合 swagger-ui、或使用单独部署的 swagger-ui和 /v2/api-docs返回的配置信息才能展现出您所构建的API文档。本文将在使用Swagger的基础上，再介绍一种生成静态API文档的方法，以便于构建更轻量部署和使用的API文档。

Swagger2Markup简介

Swagger2Markup是Github上的一个开源项目。该项目主要用来将Swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用，比如：AsciiDoc、Markdown、Confluence。

项目主页：https://github.com/Swagger2Markup/swagger2markup

如何使用

在使用Swagger2Markup之前，我们先需要准备一个使用了Swagger的Web项目，可以是直接使用Swagger2的项目

引入依赖

 <dependency>

    <groupId>io.github.swagger2markup</groupId>

    <artifactId>swagger2markup</artifactId>

    <version>1.3.1</version>

</dependency>

<repositories>


<repository>


<snapshots>


<enabled>true</enabled>


<updatePolicy>always</updatePolicy>


</snapshots>


<id>jcenter-releases</id>


<name>jcenter</name>


<url>http://jcenter.bintray.com</url>


</repository>


</repositories>

编写一个单元测试用例来生成执行生成文档的代码

 @RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)

 public class SwaggerDemoApplicationTests {
 <span class="hljs-comment">/**

  * 生成AsciiDocs格式文档

  * </span><a href="https://github.com/throws" title="@throws" class="at-link"><span class="hljs-comment"><span class="hljs-doctag">@throws</span></span></a><span class="hljs-comment"> Exception

  */</span>

 <a href="https://github.com/Test" title="@Test" class="at-link"><span class="hljs-meta">@Test</span></a>

 <span class="hljs-function"><span class="hljs-keyword">public</span> <span class="hljs-keyword">void</span> <span class="hljs-title">generateAsciiDocs</span><span class="hljs-params">()</span> <span class="hljs-keyword">throws</span> Exception </span>{

     <span class="hljs-comment">//    输出Ascii格式</span>

     Swagger2MarkupConfig config = <span class="hljs-keyword">new</span> Swagger2MarkupConfigBuilder()

             .withMarkupLanguage(MarkupLanguage.ASCIIDOC)

             .withOutputLanguage(Language.ZH)

             .withPathsGroupedBy(GroupBy.TAGS)

             .withGeneratedExamples()

             .withoutInlineSchema()

             .build();

     Swagger2MarkupConverter.from(<span class="hljs-keyword">new</span> URL(<span class="hljs-string">"http://localhost:8080/v2/api-docs"</span>))

             .withConfig(config)

             .build()

             .toFolder(Paths.get(<span class="hljs-string">"./docs/asciidoc/generated"</span>));

 }

 <span class="hljs-comment">/**

  * 生成Markdown格式文档

  * </span><a href="https://github.com/throws" title="@throws" class="at-link"><span class="hljs-comment"><span class="hljs-doctag">@throws</span></span></a><span class="hljs-comment"> Exception

  */</span>

 <a href="https://github.com/Test" title="@Test" class="at-link"><span class="hljs-meta">@Test</span></a>

 <span class="hljs-function"><span class="hljs-keyword">public</span> <span class="hljs-keyword">void</span> <span class="hljs-title">generateMarkdownDocs</span><span class="hljs-params">()</span> <span class="hljs-keyword">throws</span> Exception </span>{

     <span class="hljs-comment">//    输出Markdown格式</span>

     Swagger2MarkupConfig config = <span class="hljs-keyword">new</span> Swagger2MarkupConfigBuilder()

             .withMarkupLanguage(MarkupLanguage.MARKDOWN)

             .withOutputLanguage(Language.ZH)

             .withPathsGroupedBy(GroupBy.TAGS)

             .withGeneratedExamples()

             .withoutInlineSchema()

             .build();

     Swagger2MarkupConverter.from(<span class="hljs-keyword">new</span> URL(<span class="hljs-string">"http://localhost:8080/v2/api-docs"</span>))

             .withConfig(config)

             .build()

             .toFolder(Paths.get(<span class="hljs-string">"./docs/markdown/generated"</span>));

 }

        /**

         * 生成Confluence格式文档

         * @throws Exception

         */

        @Test

        public void generateConfluenceDocs() throws Exception {

            //    输出Confluence使用的格式

            Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()

                    .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)

                    .withOutputLanguage(Language.ZH)

                    .withPathsGroupedBy(GroupBy.TAGS)

                    .withGeneratedExamples()

                    .withoutInlineSchema()

                    .build();

            Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))

                    .withConfig(config)

                    .build()

                    .toFolder(Paths.get("./docs/confluence/generated"));

        }

        /**

         * 生成AsciiDocs格式文档,并汇总成一个文件

         * @throws Exception

         */

        @Test

        public void generateAsciiDocsToFile() throws Exception {

            //    输出Ascii到单文件

            Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()

                    .withMarkupLanguage(MarkupLanguage.ASCIIDOC)

                    .withOutputLanguage(Language.ZH)

                    .withPathsGroupedBy(GroupBy.TAGS)

                    .withGeneratedExamples()

                    .withoutInlineSchema()

                    .build();

            Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))

                    .withConfig(config)

                    .build()

                    .toFile(Paths.get("./docs/asciidoc/generated/all"));

        }

        /**

         * 生成Markdown格式文档,并汇总成一个文件

         * @throws Exception

         */

        @Test

        public void generateMarkdownDocsToFile() throws Exception {

            //    输出Markdown到单文件

            Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()

                    .withMarkupLanguage(MarkupLanguage.MARKDOWN)

                    .withOutputLanguage(Language.ZH)

                    .withPathsGroupedBy(GroupBy.TAGS)

                    .withGeneratedExamples()

                    .withoutInlineSchema()

                    .build();

            Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))

                    .withConfig(config)

                    .build()

                    .toFile(Paths.get("./docs/markdown/generated/all"));

    }

使用maven插件生成HTML文档

 <plugins>

         <plugin>

             <groupId>org.asciidoctor</groupId>

             <artifactId>asciidoctor-maven-plugin</artifactId>

             <version>1.5.6</version>

             <configuration>

                 <sourceDirectory>./docs/asciidoc/generated</sourceDirectory>

                 <outputDirectory>./docs/asciidoc/html</outputDirectory>

                 <headerFooter>true</headerFooter>

                 <doctype>book</doctype>

                 <backend>html</backend>

                 <sourceHighlighter>coderay</sourceHighlighter>

                 <attributes>

                     <!--菜单栏在左边-->

                     <toc>left</toc>

                     <!--多标题排列-->

                     <toclevels>3</toclevels>

                     <!--自动打数字序号-->

                     <sectnums>true</sectnums>

                 </attributes>

             </configuration>

         </plugin>

 </plugins>

效果

实际项目应用后效果

[实际项目应用后效果](http://cdn-blog.jetbrains.org.cn/doc/all.html）

代码

https://github.com/changdaye/swagger-demo

鸣谢

文章出处： http://blog.didispace.com/swagger2markup-asciidoc/

码农公寓

说明

Swagger2Markup简介

如何使用

效果

实际项目应用后效果

代码

鸣谢

相关文章