Swagger2 offline documentation: swagger2markup code and plugin method

Internet 2020-04-15 11:09:37 views: null

table of Contents

Swagger article summary

Introduction to Swagger2Markup

Project version description:

swagger2markup code way

Step 1: Edit pom.xml to add related dependencies and repositories that need to be used

Step 2: Write a unit test case to generate code that executes the generated documentation

Generate AsciiDoc

Generate markdown

Generate Confluence

swagger2markup plugin method

Generate asciidoc or markdown documents

Add swagger2markup plugin

Generate asciidoc or markdown documents

Related instructions

Generate HTML documents

Add asciidoctor plugin

Generate HTML documents

Generate PDF documents

Add asciidoctor plugin

Generate PDF documents

Solve the problem of garbled and blank PDF:

Generate HTML and PDF documents at the same time

Add plugin

Generate HTML and PDF documents at the same time

Swagger article summary

Introduction to Swagger2Markup

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

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

Project version description:

  • spring boot 2.0.x
  • swagger 2.8.0

swagger2markup code way

Step 1: Edit and pom.xmladd related dependencies and repositories that need to be used

<dependency>
	<groupId>io.github.swagger2markup</groupId>
	<artifactId>swagger2markup</artifactId>
	<version>1.3.1</version>
</dependency>

Which depends on the components, these two should pay attention to, in the offline development environment, you need to manually add it to the local warehouse

    <dependency>
      <groupId>nl.jworks.markdown_to_asciidoc</groupId>
      <artifactId>markdown_to_asciidoc</artifactId>
      <version>1.0</version>
      <scope>compile</scope>
    </dependency>

    <dependency>
      <groupId>nl.jworks.markdown_to_asciidoc</groupId>
      <artifactId>markdown_to_asciidoc</artifactId>
      <version>1.0</version>
      <scope>compile</scope>
    </dependency>

Step 2: Write a unit test case to generate code that executes the generated documentation

Generate AsciiDoc

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

    @Test
    public void generateAsciiDocs() throws Exception {
        //    输出Ascii格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .build();

        Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("src/docs/asciidoc/generated"));
    }

}
  • Generated by Java code: only need to modify withMarkupLanguageattributes to specify different formats and toFolderattributes to specify different output directories for the results.

Generate markdown

Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
    .withMarkupLanguage(MarkupLanguage.MARKDOWN)
    .build();

Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
    .withConfig(config)
    .build()
    .toFolder(Paths.get("src/docs/markdown/generated"));

Generate Confluence

Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
    .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
    .build();

Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
    .withConfig(config)
    .build()
    .toFolder(Paths.get("src/docs/confluence/generated"));

The content of the above code is very simple and outlines a few key contents:

  • MarkupLanguage.ASCIIDOC: Specifies the final format to be output. In addition to ASCIIDOC, there are MARKDOWN and CONFLUENCE_MARKUP
  • from(new URL("http://localhost:8080/v2/api-docs"): Specify the source configuration for generating static deployment documents, which can be in the form of a URL or a String type that conforms to the Swagger specification or a stream read from a file. If it is the current Swagger project, we use the way to access the local Swagger interface. If it is the Swagger document configuration file obtained from the outside, you can use the string or read the file.
  • toFolder(Paths.get("src/docs/asciidoc/generated"): Specify the specific directory location of the final generated file

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

AsciiDoc

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

Markdown and Confluence

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 that four different static files are generated after this method is run.

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.

swagger2markup plugin method

Generate asciidoc or markdown documents

Add swagger2markup plugin

<plugin>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>1.3.3</version>
                <configuration>
                    <swaggerInput>http://localhost:9210/v2/api-docs</swaggerInput>
                    <!-- 生成asciidoc格式 -->
                    <outputFile>src/docs/asciidoc/generated/all</outputFile>
<!--                    <outputDir>src/docs/asciidoc/generated</outputDir>-->
                    <!-- 生成markdown格式 -->
<!--                    <outputFile>src/docs/markdown/generated/all</outputFile>-->
                    <config>
                        <!-- 生成asciidoc格式 -->
                        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                        <!-- 生成markdown格式 -->
<!--                        <swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage>-->
                        <swagger2markup.outputLanguage>ZH</swagger2markup.outputLanguage>
                        <swagger2markup.generatedExamplesEnabled>true</swagger2markup.generatedExamplesEnabled>
                        <swagger2markup.inlineSchemaEnabled>false</swagger2markup.inlineSchemaEnabled>
                        <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
                    </config>
                </configuration>
            </plugin>

Generate asciidoc or markdown documents

  • Run the project
  • Execute swagger2markup plugin: maven window: Plugins.swagger2markup under the specified project

Related instructions

  • swaggerInput : The interface json data file generated by swagger.
  • Output :
    • outputFile: output to a single file
    • outputDir: output to the specified file
  • swagger2markup.markupLanguage : output format
  • swagger2markup.outputLanguage : language type: such as Chinese (ZH), default English (EN)
  • swagger2markup.generatedExamplesEnabled : Specifies whether HTTP request and response examples should be generated, default false
  • swagger2markup.inlineSchemaEnabled : Whether to enable parameter inlining
  • swagger2markup.pathsGroupedBy : api sorting rules are generally sorted by tags

Swagger2markup plugin configuration instructions

http://swagger2markup.github.io/swagger2markup/1.3.3/#_swagger2markup_properties

Generate asciidoc or markdown documents

Generate HTML documents

Add asciidoctor plugin

<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>html5</backend>
                    <attributes>
                        <!--导航栏在左-->
                        <toc>left</toc>
                        <!--显示层级数-->
                        <toclevels>3</toclevels>
                        <!--自动打数字序号-->
                        <sectnums>true</sectnums>
                    </attributes>
                </configuration>
            </plugin>

Generate HTML documents

  • Generate asciidoc documents
  • Execute plugin: maven window: Plugins.asciidoctor.asciidoctor: process-asciidoc under the specified project

Related instructions

  • sourceDirectory : the directory where the asciidoc document is located
  • outputDirectory : HTML output directory
  • backend : type
Generate HTML documents

Generate PDF documents

Add asciidoctor plugin

<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/pdf</outputDirectory>
                    <backend>pdf</backend>
                </configuration>
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>1.5.0-alpha.16</version>
                    </dependency>
                </dependencies>
            </plugin>

Generate PDF documents

  • Generate asciidoc documents
  • Execute plugin: maven window: Plugins.asciidoctor.asciidoctor: process-asciidoc under the specified project

Solve the problem of garbled and blank PDF:

The PDF is garbled and blank

  • The asciidoctorj-pdf jar package in the maven repository, use the compression tool to open:

    • Enter asciidoctorj-pdf-1.5.0-alpha.16.jar \ gems \ asciidoctor-pdf-1.5.0.alpha.16 \ data \ directory
    • fonts: font file directory
    • themes: configuration file directory

  • Download font:

    • Font download: https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic/releases
    • Note: Simply download KaiGenGothicCN-Bold.It, KaiGenGothicCN-Bold-Italic.ttf, KaiGenGothicCN-Bold-Italic.ttf, KaiGenGothicCN-Bold-Italic.ttf
    • Put the font file in the fonts directory

  • Change setting

    • Enter the themes directory and modify the default-theme.yml file
    • Modify the font file configuration corresponding to the base: font_family attribute value: under font: catalog.
    base:
  font_family: Noto Serif

font:
  catalog:
    Noto Serif:
      normal: KaiGenGothicCN-Regular.ttf
      bold: KaiGenGothicCN-Bold.ttf
      italic: KaiGenGothicCN-Regular-Italic.ttf
      bold_italic: KaiGenGothicCN-Bold-Italic.ttf

Generate HTML and PDF documents at the same time

Add plugin

<plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.6</version>
                <configuration>
                  <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
                </configuration>
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>1.5.0-alpha.16</version>
                    </dependency>
                </dependencies>
                <executions>
                    <execution>
                        <id>output-html</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>html5</backend>
                       <outputDirectory>src/docs/asciidoc/html</outputDirectory>
                            <attributes>
                                <!--导航栏在左-->
                                <toc>left</toc>
                                <!--显示层级数-->
                                <toclevels>3</toclevels>
                                <!--自动打数字序号-->
                                <sectnums>true</sectnums>
                            </attributes>
                        </configuration>
                    </execution>
                    <execution>
                        <id>output-pdf</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>pdf</backend>
                        <outputDirectory>src/docs/asciidoc/pdf</outputDirectory>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

Generate HTML and PDF documents at the same time

  • Generate asciidoc documents
  • Execute plugin: maven window: Plugins.asciidoctor.asciidoctor: process-asciidoc under the specified project
  • Generate documentation (choose one of the two): Note: This step takes time, about seven or eight minutes
    • Run the command mvn generate-resources
    • Use idea to set up a quick start: run / debug configurations-> maven-> command line: generate-resources, execute

PDFPDF has garbled and blank issues

  • Refer to separate PDF generation problem solving

Related instructions

  • executions : multiple execution task configurations
  • execution.id : not repeatable
  • Other : Refer to the instructions for separately generating HTML and PDF

 

Reference link:

http://blog.didispace.com/swagger2markup-markdown-confluence/

Qi Yan Blog Expert
发布了430 篇原创文章 · 获赞 1473 · 访问量 394万+
他的留言板 关注

Guess you like

Origin blog.csdn.net/fly910905/article/details/105504324
Recommended
Ranking
Big Data Development-Flume-Access Hive Data Warehouse Construction Process
Week Twelve blog jobs
Jmeter plug-in PerfMon Metrics Collector installation and use and error resolution
fastjson vulnerability research deserialization (at)
Summary of errors encountered by IDEA using Tomcat
SAP ABAP Excel import data download template example
[SpringBoot] System Description
GPU memory hierarchy (gpu memory hierarchy)
Common Commands in Linux
Flowable process history display modification based on jeecg-boot
Daily
More
2024-08-28(0)
2024-08-27(0)
2024-08-26(0)
2024-08-25(0)
2024-08-24(0)
2024-08-23(0)
2024-08-22(0)
2024-08-21(0)
2024-08-20(0)
2024-08-19(0)

Code World

© 2018 codetd.com