Export swagger2 document to HTML or markdown format for offline reading

Time:2020-11-19

Export swagger2 document to HTML or markdown format for offline reading

There are many articles on “building API document using swagger2” on the Internet. The document is an online document and needs to be accessed using HTTP. However, when we use the swagger interface document, sometimes we need to access the interface document offline, such as exporting the document to HTML and markdown format. Or we don’t want the application system to use the same service as the swagger interface document, but export HTML and deploy it separately. This ensures that the access to the interface document does not affect the business system, and improves the security of the interface document to a certain extent. The core implementation process is as follows:

  • In the application of swagger2 interface document, the interface document can be exported to ADOC file or markdown file by using swagger2markup.
  • Then the ADOC file is converted into static HTML format, and HTML can be published to nginx or other web application containers to provide access (this article will not talk about static HTML deployment, only HTML export).

Note: ADOC is a file format, not my pen fault. It’s not a doc file, it’s not a docx file.

1、 Maven dependent class library

In the application that has integrated swagger2, the related dependency class library is introduced through Maven coordinate, pom.xml The code is as follows:

<dependency>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup</artifactId>
    <version>1.3.1</version>
</dependency>
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-core</artifactId>
    <version>1.5.16</version>
</dependency>
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-models</artifactId>
    <version>1.5.16</version>
</dependency>

Swagger2markup is used to export swagger2 online interface documents to HTML, markdown, ADOC and other formats for static deployment or offline reading. The first Maven coordinate is required. The last two Maven coordinates are used when you report the error in the following figure during the execution of the following code, or when some classes cannot be imported.

Export swagger2 document to HTML or markdown format for offline reading

The reason for the exception has been explained on GitHub’s issues: when you use the swagger core version greater than or equal to 1.5.11, and the swagger models version is less than 1.5.11, an exception will occur. So we explicitly introduce these two jars, replacing the two jars introduced by swagger2 by default.

Export swagger2 document to HTML or markdown format for offline reading

2、 Generate ADOC format file

The following code is realized by encoding to generate ADOC format file

@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
public class DemoApplicationTests {
    @Test
    public void generateAsciiDocs() throws Exception {
        //Output ASCII format
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage( MarkupLanguage.ASCIIDOC )// set generation format
                .withOutputLanguage( Language.ZH )// set language Chinese or other languages
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL("http://localhost:8888/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(Paths.get("src/main/resources/docs/asciidoc"));
    }
}
  • Use runwith annotation and springboottest annotation to start the application service container. SpringBootTest.WebEnvironment.DEFINED_ Port means to use application.yml It’s important to define the port instead of randomly using one port for testing.
  • Swagger2markupconfig is the configuration of the output file, such as the format of the file and the natural language in the file
  • The from of swagger2markupconverter indicates which HTTP service is the source of the resource export (JSON format). You can visit this link yourself. 8888 is my service port, which needs to be modified according to your own application configuration.
  • Tofile indicates the location where the exported file will be stored without adding a suffix. You can also use tofolder to indicate the path where the file is exported. The difference between them is that tofolder is used to export multiple files classified by tags in the file directory, while tofile is used to export a file (the collection of multiple tofolder files).
@Test
public void generateMarkdownDocsToFile() throws Exception {
    //Output markdown to single file
    Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
            .withMarkupLanguage(MarkupLanguage.MARKDOWN)
            .withOutputLanguage(Language.ZH)
            .withPathsGroupedBy(GroupBy.TAGS)
            .withGeneratedExamples()
            .withoutInlineSchema()
            .build();

    Swagger2MarkupConverter.from(new URL("http://localhost:8888/v2/api-docs"))
            .withConfig(config)
            .build()
            .toFile(Paths.get("src/main/resources/docs/markdown"));
}

The above code is the code to generate the interface file in markdown format. After executing the above two sections of unit test code, the corresponding format interface files can be produced.

Another way is to generate interface files in the form of ADOC and markdown through Maven plug-in. The author does not often use this method, does not use the code generation method, the configuration is flexible, many configurations are placed in pom.xml I feel bloated. But let’s introduce it. First, configure the Maven plug-in swagger2markup Maven plugin.

<plugin>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>1.3.1</version>
    <configuration>
        <swaggerInput> http://localhost : 8888 / V2 / API doc < / swaggerinput > <! --- swagger API JSON path -- >
        < outputdir > Src / main / resources / Doc / asciidoc < / outputdir > <! --- generation path -- >
        <config>
            <swagger2 markup.markupLanguage >ASCIIDOC</swagger2 markup.markupLanguage ><! -- generation format -- >
        </config>
    </configuration>
</plugin>

Then run the plug-in, as shown in the following figure:

Export swagger2 document to HTML or markdown format for offline reading

3、 Generating HTML document by Maven plug-in

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.6</version>
    <configuration>
         <! -- asciidoc file directory -- >
        <sourceDirectory>src/main/resources/docs</sourceDirectory>
        <! --- path to generate HTML -- >
        <outputDirectory>src/main/resources/html</outputDirectory>
        <backend>html</backend>
        <sourceHighlighter>coderay</sourceHighlighter>
        <attributes>
            <! -- navigation bar on left -- >
            <toc>left</toc>
            <! -- display layer series -- >
            <!--<toclevels>3</toclevels>-->
            <! -- automatic number printing
            <sectnums>true</sectnums>
        </attributes>
    </configuration>
</plugin>

The source directory path of the ADOC must be the same as that of the ADOC file generated in Section 3. Then run the plug-in as shown in the figure below.

Export swagger2 document to HTML or markdown format for offline reading

The display effect of HTML interface document is as follows. With HTML interface document, it is very convenient for you to convert it into other document formats. There are many tools to use. I will not introduce them here.

Export swagger2 document to HTML or markdown format for offline reading

Looking forward to your attention

  • Recommend to you a series of documents of bloggers: “teach you to learn spring boot series by hand – 16 chapters and 97 sections”
  • This article reprints to indicate the source (must take the link, cannot only turn the text): letter brother blog.