In addition to Weibo, there is also WeChat
Please pay attention
WeChat public account
Shulou
2025-01-26 Update From: SLTechnology News&Howtos shulou NAV: SLTechnology News&Howtos > Internet Technology >
Share
Shulou(Shulou.com)06/02 Report--
This article focuses on "Swagger static document generation method", interested friends may wish to have a look. The method introduced in this paper is simple, fast and practical. Next let the editor to take you to learn the "Swagger static document generation method" bar!
Introduction to Swagger2Markup
Swagger2Markup is an open source project on Github. This project is mainly used to convert Swagger automatically generated documents into several popular formats for static deployment and use, such as AsciiDoc, Markdown, Confluence.
Project home page: https://github.com/Swagger2Markup/swagger2markup
How to use
Before using Swagger2Markup, we need to prepare a Web project that uses Swagger, either directly using Swagger2 or using the project built in the article Spring Boot 2.x basic tutorial: building strong API documents with Swagger2. Readers can obtain it through the following warehouse:
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 chapter2-2 module in this project as a basis to generate static documents in several different formats.
Generate AsciiDoc documents
There are two ways to generate AsciiDoc documents:
Generated by Java code
Step 1: edit pom.xml to increase the dependencies and repositories you need to use
... Io.github.swagger2markup swagger2markup 1.3.3 test false jcenter-releases jcenter http://jcenter.bintray.com
The tool itself is mainly used temporarily, so here we set scope to test so that the dependency is not packaged into the normal running environment.
Step 2: write a unit test use case to generate the code that executes the 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 ") / / output Ascii format Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder () .withMarkupLanguage (MarkupLanguage.ASCIIDOC) .build (); Swagger2MarkupConverter.from (remoteSwaggerFile) .withConfig (config) .build () .toFolder (outputDirectory);}}
The above code is simple and roughly illustrates several key elements:
MarkupLanguage.ASCIIDOC: specifies the final format to output. In addition to ASCIIDOC, there are MARKDOWN and CONFLUENCE_MARKUP, which define other formats, which will be illustrated later.
From (remoteSwaggerFile: specifies the source configuration that generates the static deployment document, which can be in the form of URL, a String type that conforms to the Swagger specification, or a stream read from a file. If it is a Swagger project currently in use, we can access the local Swagger interface by using a string or read the file if the Swagger document configuration file is obtained from the outside.
ToFolder (outputDirectory): specify the specific directory location of the final generated file
After executing the above test case, we can get the following in the src directory of the current project:
Src--docs----asciidoc------generated--------definitions.adoc--------overview.adoc--------paths.adoc--------security.adoc
As you can see, this approach generates four different static files after running.
Export to a single file
If you do not want to split the result file, you can also output the conversion results to a single file by replacing toFolder (Paths.get ("src/docs/asciidoc/generated") to toFile (Paths.get ("src/docs/asciidoc/generated/all")), so that the final html can be generated in a single file.
Generate through the Maven plug-in
In addition to the way it is generated by writing Java code above, swagger2markup also provides a corresponding Maven plug-in to use. For the above generation method, you can complete the generation of static content by adding the following plug-ins to pom.xml.
Io.github.swagger2markup swagger2markup-maven-plugin 1.3.3 http://localhost:8080/v2/api-docs src/docs/asciidoc/generated-by-plugin ASCIIDOC
Before using the plug-in to generate, you need to start the application. Then execute the plug-in and you can see that the same adoc file as above is generated in the src/docs/asciidoc/generated-by-plugin directory.
Generate HTML
After you have completed the conversion from the Swagger document configuration file to the AsciiDoc source file, it is how to convert the AsciiDoc into deployable HTML content. Here we continue to introduce a Maven plug-in on the basis of the above project.
Org.asciidoctor asciidoctor-maven-plugin 1.5.6 src/docs/asciidoc/generated src/docs/asciidoc/html html coderay left
With the above configuration, after executing the plug-in's asciidoctor:process-asciidoc command, you can generate the final available static deployment HTML in the src/docs/asciidoc/html directory. After the generation is completed, you can view it directly through the browser, and you can see the static deployment result similar to the following figure:
Does it feel like deja vu? Yes, the same is true of documents before the E version of Spring Cloud!
Support for Markdown and Confluence
The way to generate Markdown and Confluence is very simple, similar to the method in the previous article, you only need to modify one parameter.
Generate Markdown and Confluence documents
There are two ways to generate:
Generated by Java code: you only need to modify the withMarkupLanguage attribute to specify a different format and the toFolder attribute to specify a different output directory for the result.
Generate a code snippet of markdown:
URL remoteSwaggerFile = new URL ("http://localhost:8080/v2/api-docs");Path outputDirectory = Paths.get (" src/docs/markdown/generated "); / / output Ascii format Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder () .withMarkupLanguage (MarkupLanguage.MARKDOWN) .build (); Swagger2MarkupConverter.from (remoteSwaggerFile) .withConfig (config) .build () .toFolder (outputDirectory)
Generate a code snippet of confluence:
URL remoteSwaggerFile = new URL ("http://localhost:8080/v2/api-docs");Path outputDirectory = Paths.get (" src/docs/confluence/generated "); / / output Ascii format Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder () .withMarkupLanguage (MarkupLanguage.CONFLUENCE_MARKUP) .build (); Swagger2MarkupConverter.from (remoteSwaggerFile) .withConfig (config) .build () .toFolder (outputDirectory)
After executing the above settings, we can get the following in the src directory of 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
You can see that after running, the converted contents in different formats are output in the markdown and confluence directories, respectively. If the reader wants to generate through the plug-in, refer directly to the previous section and simply modify the swagger2markup.markupLanguage in the plug-in configuration to support the output of other formats.
Finally, let's take a look at how to use the generated Markdown and Confluence documents
Deployment of Markdown
At present, Markdown is commonly used in documentation, so there are many static deployment tools available, such as Hexo, Jekyll, etc. you can easily achieve static deployment, or you can use some SaaS documentation tools, such as Voice, etc. Specific usage, here according to the documentation of these tools are very detailed, here will not be introduced in detail.
Deployment of Confluence
It is believed that many teams use Confluence as their document management system, so let's talk about the use of Confluence format to generate results.
Step 1: select {} Markup in the toolbar of the new page of Confluence
Step 2: select Confluence Wiki in the Insert option of the pop-up box, and then paste the contents of the generated txt file in the input box on the left; at this point, you can see the effect of the following figure in the reading box on the right.
Note: so the Markdown format is also provided in the Insert option, and we can also use the Markdown results generated above, but the results are not good, so it is better to use special generation results in Confluence.
At this point, I believe that everyone on the "Swagger static document generation method" have a deeper understanding, might as well to the actual operation of it! Here is the website, more related content can enter the relevant channels to inquire, follow us, continue to learn!
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.
Views: 213
*The comments in the above article only represent the author's personal views and do not represent the views and positions of this website. If you have more insights, please feel free to contribute and share.
Continue with the installation of the previous hadoop.First, install zookooper1. Decompress zookoope
"Every 5-10 years, there's a rare product, a really special, very unusual product that's the most un
© 2024 shulou.com SLNews company. All rights reserved.