table of Contents
Introduction to Swagger2Markup
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 or markdown documents
Generate asciidoc or markdown documents
Solve the problem of garbled and blank PDF:
Generate HTML and PDF documents at the same time
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.xml
add 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
withMarkupLanguage
attributes to specify different formats andtoFolder
attributes 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_MARKUPfrom(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
![](https://img-blog.csdnimg.cn/20200414095138153.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ZseTkxMDkwNQ==,size_16,color_FFFFFF,t_70)
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
![](https://img-blog.csdnimg.cn/2020041409533033.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ZseTkxMDkwNQ==,size_16,color_FFFFFF,t_70)
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
![](https://img-blog.csdnimg.cn/20200414100423536.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ZseTkxMDkwNQ==,size_16,color_FFFFFF,t_70)
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:
![](https://img-blog.csdnimg.cn/20200414095437838.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ZseTkxMDkwNQ==,size_16,color_FFFFFF,t_70)
-
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/