Spring Boot 2.x basis: Swagger generate static documents

Foreword

By Swagger after the previous two articles on entry and introduced the use of specific details, we have been able easily to Spring MVC Web project automatically build the API documentation. If you are not familiar with this, you can read:

• Spring Boot 2.x Basics Tutorial: Using Swagger2 build powerful API documentation
• Spring Boot 2.x based tutorial: Swagger Interface Classification and each element Detailed Scheduling

In these two articles, we must build document integration in the project swagger-ui, or use a separate deployment swagger-uiand /v2/api-docsconfiguration information returned by the API documentation to show that you build. And sometimes, we may only need to provide a static document to another when docking party, how do we generate static API documentation fast and lightweight it?

Next we have to learn a tool to solve this problem: Swagger2Markup .

Swagger2Markup Profile

Swagger2Markup is an open source project on Github. The project is mainly used to convert Swagger automatically generated document into several popular formats for static deployment and use, such as: AsciiDoc, Markdown, Confluence.

Project Home: https://github.com/Swagger2Markup/swagger2markup

how to use

Before using Swagger2Markup, we first need to prepare a Swagger uses the Web project, can be used directly Swagger2 project, you can use Spring Boot 2.x Basics Tutorial: Using Swagger2 build powerful API documentation project in an article constructed. Readers can obtain the following repository:

• Github：https://github.com/dyc87112/SpringBoot-Learning/tree/2.x
• Gitee：https://gitee.com/didispace/SpringBoot-Learning/tree/2.x

Next, we will use the project chapter2-2module as a basis to generate static documents several different formats.

AsciiDoc document generation

There are two ways to generate AsciiDoc document:

To generate Java code

The first step : Editing pom.xmlassociated with an increased dependence and require the use of warehouse

<dependencies>
    ...

    <dependency>
        <groupId>io.github.swagger2markup</groupId>
        <artifactId>swagger2markup</artifactId>
        <version>1.3.3</version>
        <scope>test</scope>
    </dependency>
</dependencies>

<repositories>
    <repository>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
        <id>jcenter-releases</id>
        <name>jcenter</name>
        <url>http://jcenter.bintray.com</url>
    </repository>
</repositories>

The tool itself mainly on the temporary use of it, so here we are put scopeto test, so this does not depend on package to the normal operating environment.

Step two : write a unit test code to generate execution generated document

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

    @Test
    public void generateAsciiDocs() throws Exception {

        URL remoteSwaggerFile = new URL("http://localhost:8080/v2/api-docs");
        Path outputDirectory = Paths.get("src/docs/asciidoc/generated");

        //    输出Ascii格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .build();


        Swagger2MarkupConverter.from(remoteSwaggerFile)
                .withConfig(config)
                .build()
                .toFolder(outputDirectory);
    }

}

This code is very simple, general description of several key elements:

• MarkupLanguage.ASCIIDOC: Specifies the final format to be output. In addition ASCIIDOC, there are MARKDOWNand CONFLUENCE_MARKUP, respectively, define the other formats, a specific example will later.
• from(remoteSwaggerFile: Specifies the source document to generate a static deployment configuration, this is the URL form, it can be standardized in line with Swagger String type or read from a file stream. If Swagger project is currently in use, the way we access through the use of local Swagger interface, if it is acquired from the outside Swagger document profile, you can read the way through a string or file
• toFolder(outputDirectory): Specifies the final generation of the specific file directory location

After executing the above test, we can get the following in the src directory under the current project:

src
--docs
----asciidoc
------generated
--------definitions.adoc
--------overview.adoc
--------paths.adoc
--------security.adoc

It can be seen in this way is generated after running out of 4 different static files.

Output to a single file

If you do not want to split the result file, it may be replaced by toFolder(Paths.get("src/docs/asciidoc/generated")as toFile(Paths.get("src/docs/asciidoc/generated/all"))the conversion result is output to a single file, which can also ultimately generate a single html.

Generated by Maven plug-ins

In addition to the above manner to the preparation of Java code generated, swagger2markup Maven plug is also provided corresponding use. For generating the above manner, it can by pom.xmlused to complete the generation of static content increases as the plug.

<plugin>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>1.3.3</version>
    <configuration>
        <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
        <outputDir>src/docs/asciidoc/generated-by-plugin</outputDir>
        <config>
            <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
        </config>
    </configuration>
</plugin>

Before using the plugin generates, you need to start the application. Then execute plug-in, you can src/docs/asciidoc/generated-by-pluginsee the directory also generated as above adoc files.

HTML generation

After the completion of the source file from Swagger document profile to AsciiDoc conversion AsciiDoc it is how to convert HTML content into a deployable. Here continue in the project on the basis of the above, the introduction of a Maven plugin to complete.

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.6</version>
    <configuration>
        <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
        <outputDirectory>src/docs/asciidoc/html</outputDirectory>
        <backend>html</backend>
        <sourceHighlighter>coderay</sourceHighlighter>
        <attributes>
            <toc>left</toc>
        </attributes>
    </configuration>
</plugin>

By the above configuration, the plug-executed asciidoctor:process-asciidocafter the command, you will be able to src/docs/asciidoc/htmlgenerate the final deployment of the available static HTML of the directory. After the completion of generation, can see directly through the browser view, you can see the results of the static deployment similar to the following:

Is it deja vu? Yes, the previous version of the document E Spring Cloud is also such! ! !

Markdown support with Confluence

To generate Markdown and Confluence of a very simple way, similar to the previous method, only you need to modify a parameter.

Markdown document generation and Confluence

There are ways to generate it in two ways:

• Java code is generated by: only need to modify withMarkupLanguageattribute to specify different formats and toFolderattributes specified directory for different output results.

Markdown of generated code fragment:

URL remoteSwaggerFile = new URL("http://localhost:8080/v2/api-docs");
Path outputDirectory = Paths.get("src/docs/markdown/generated");

//    输出Ascii格式
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
    .withMarkupLanguage(MarkupLanguage.MARKDOWN)
    .build();

Swagger2MarkupConverter.from(remoteSwaggerFile)
    .withConfig(config)
    .build()
    .toFolder(outputDirectory);

Confluence of generated code fragment:

URL remoteSwaggerFile = new URL("http://localhost:8080/v2/api-docs");
Path outputDirectory = Paths.get("src/docs/confluence/generated");

//    输出Ascii格式
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
    .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
    .build();

Swagger2MarkupConverter.from(remoteSwaggerFile)
    .withConfig(config)
    .build()
    .toFolder(outputDirectory);

After performing the setting contents of the above, we can get the following in the src directory under the current project:

src
--docs
----confluence
------generated
--------definitions.txt
--------overview.txt
--------paths.txt
--------security.txt
----markdown
------generated
--------definitions.md
--------overview.md
--------paths.md
--------security.md

It can be seen after running output the contents of the conversion of different formats in markdown and confluence directory. If the reader wants to generate through plug-ins, a direct reference to the content, only need to modify the plug configuration swagger2markup.markupLanguagecan support other output formats content.

Finally, we take a look at the generated Markdown documents and how to use Confluence

Markdown deployment

Markdown currently used in the preparation of the document is very common, so it can be static deployment tools are also very large, such as: Hexo, Jekyll and so can easily achieve static deployment, you can also use some SaaS version of the document tools, such as: bird and other language . Specific use, according to a document where these tools are very detailed, not specifically described here.

Confluence of deployment

I believe that many teams are using Confluence as a document management system, so the following format specifically talk about using Confluence to generate results.

The first step : Select the toolbar of the new Confluence page{}Markup

Step Two : In the dialog box Insertoptions selected Confluence Wiki, then the contents generated txt file, input box on the left paste; in this case, the box on the right reading the following effects can be seen in the FIG.

Note: So the Insertoption is also available in Markdown format, we can also use the results generated by Markdown above, but the effect is not good, so the use of specialized generate better results in the Confluence.

The sample code

The complete works of this paper can be viewed below repository chapter2-5directory:

• Github：https://github.com/dyc87112/SpringBoot-Learning/tree/2.x
• Gitee：https://gitee.com/didispace/SpringBoot-Learning/tree/2.x

If you think this article is good, welcome Star support, your concern is I insist on the power!

Reference material

• [1] https://github.com/Swagger2Markup/swagger2markup
• [2] http://blog.didispace.com/swagger2markup-asciidoc/
• [3] http://blog.didispace.com/swagger2markup-markdown-confluence/

I welcome the attention of the public number: Program ape DD, get exclusive organize learning resources and push dry goods daily.
If you are interested in my topic content, you can focus on my blog: didispace.com