Shulou(Shulou.com)06/03 Report--

In this issue, the editor will bring you about how to export Swagger2 documents to HTML or markdown and other formats for offline reading. The article is rich in content and analyzes and describes for you from a professional point of view. I hope you can get something after reading this article.

In our daily use of swagger interface documents, sometimes we need to access the interface documents offline, such as exporting the documents to html or markdown format. Or we do not want the application system to use the same service as the swagger interface document, but deploy separately after exporting the HTML, which 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:

In the application where the swagger2 interface document is located, use swagger2markup to export the interface document to an adoc file, or you can export a markdown file. Then convert the adoc file to a static html format, and you can publish the html to nginx or other web application containers to provide access (this article will not talk about html static deployment, only HTML export).

Note: adoc is a file format, not my clerical error. Not a doc file or a docx file.

1. Maven dependent class library

In applications where swagger2 has been integrated, relevant dependent class libraries are introduced through maven coordinates. The pom.xml code is as follows:

Io.github.swagger2markup swagger2markup 1.3.1 io.swagger swagger-core 1.5.16 io.swagger swagger-models 1.5.16

Swagger2markup is used to export swagger2 online interface documents to html,markdown,adoc and other format documents 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 import.

The cause of the exception has been explained on github's issues: an exception occurs when you use swagger-core version greater than or equal to 1.5.11 and swagger-models version less than 1.5.11. So we explicitly introduce these two jar, replacing the two jar introduced by swagger2 by default.

Second, generate adoc format files

The following code is a coded way to generate a file in adoc format

@ 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) / / sets the generation format .withOutputLanguage (Language.ZH) / sets the 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 "));}}

Start the application service container using RunWith annotations and SpringBootTest annotations. SpringBootTest.WebEnvironment.DEFINED_PORT means to use a port defined by application.yml instead of randomly using a port for testing, which is important.

Swagger2MarkupConfig is the configuration of the output file, such as the file format and the natural language in the file.

Swagger2MarkupConverter's from indicates which HTTP service is the source of 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 a suffix. You can also use toFolder to represent the path where the file export is stored. The difference between the two lies in using toFolder to export multiple files classified by label TAGS in the file directory, and using toFile is to export a file (a collection of toFolder multiple files).

@ Testpublic void generateMarkdownDocsToFile () throws Exception {/ / output Markdown to a single file Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder () .withMarkupLanguage (MarkupLanguage.MARKDOWN) .without putLanguage (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 that generates the interface file in markdown format. Execute the above 2 pieces of unit test code, and you can produce the interface file in the corresponding format.

Another way is to generate interface files in adoc and markdown formats through the maven plug-in. The author does not use this approach very often, and the configuration is flexible without using code generation, and many configurations are put into pom.xml to feel bloated. But for an introduction, first configure the maven plug-in swagger2markup-maven-plugin.

Io.github.swagger2markup swagger2markup-maven-plugin 1.3.1 http://localhost:8888/v2/api-docs src/main/resources/docs/asciidoc ASCIIDOC

Then run the plug-in, as shown below:

Generate HTML documents through the maven plug-in

Org.asciidoctor asciidoctor-maven-plugin 1.5.6 src/main/resources/docs src/main/resources/html html coderay left true

The sourceDirectory path of adoc must be the same as the path of the adoc file generated in the third section. Then run the plug-in as shown below.

The effect of the HTMl interface document is as follows. With the HTML interface document, it is too convenient for you to convert it to other documents in various formats. There are many tools available. I won't introduce them one by one here.

The above is the editor for you to share how to export Swagger2 documents to HTML or markdown format offline reading, if you happen to have similar doubts, you might as well refer to the above analysis to understand. If you want to know more about it, you are welcome to follow the industry information channel.

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.