SpringBoot2 in how to generate static documents

SpringBoot2 in how to generate static documents

In the actual development process, we can generate our interface documentation by the swagger, this document will be available to front-end personnel under development. Sometimes, however, we need to put our interface documentation, available to third party companies how to do?

I am now experiencing this problem. After the completion of our project development, mode of separation is also front and rear ends. However, third-party companies need our interface documentation, how to do? Then we need to swagger of a document, generate static documents can only be sent in the past.

Document Interface

Speaking interface documentation, we are most familiar with is swaggger it. This can easily be annotated manner, you can generate a document that we need. And you can debug interface online.

随着前后端分离架构和微服务架构的流行，我们使用Spring Boot来构建RESTful API项目的场景越来越多。通常我们的一个RESTful API就有可能要服务于多个不同的开发人员或开发团队：IOS开发、Android开发、Web开发甚至其他的后端服务等。

After the above is the start of the project, swagger to the visual interface we provide a.

swagger Project Integration

springboot integrated swagger is very simple, we only need to import dependency, and then write notes on the method on it.

Main Class adding @EnableSwagger2Docannotations, as follows

According to project needs, we can modify the default configuration of swagger

swagger.title=spring-boot-starter-swagger
swagger.description=Starter for swagger 2.x
swagger.version=1.4.0.RELEASE swagger.license=Apache License, Version 2.0 swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html swagger.termsOfServiceUrl= swagger.contact.name= swagger.contact.url= swagger.contact.email= swagger.base-package= swagger.base-path=/** 

Start the application, access: http://localhost:8080/swagger-ui.html access can be visited

Notes is simple

@Api(tags = "用户管理")
@RestController
@RequestMapping(value = "/users") // 通过这里配置使下面的映射都在/users下 public class UserController { // 创建线程安全的Map，模拟users信息的存储 static Map<Long, User> users = Collections.synchronizedMap(new HashMap<>()); @GetMapping("/") @ApiOperation(value = "获取用户列表") public List<User> getUserList() { List<User> r = new ArrayList<>(users.values()); return r; } } 

Simple interface documentation on the deployment is over, the next step is static

Static interface documentation

Swagger2Markup是Github上的一个开源项目。该项目主要用来将Swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用，比如：AsciiDoc、Markdown、Confluence。

Today is used Swagger2Markup, this plugin can help us to achieve static function.

项目主页：https://github.com/Swagger2Markup/swagger2markup

Add dependent

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

This time, we <scope> test </ scope>, this can get rid of this dependence in a formal environment.

To everyone intuitive, write a test class to complete the static.

@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); } } 

After completion of the implementation of this code, you can produce ASCIIDOC documents we need in the project directory

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

HTML generation

We mostly need is html documents for easy viewing. Next, only need to modify it to configure it.

Add plug-in dependencies

<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> 

<Backend> html </ backend> This code can be generated html documents.

The plug-in execution asciidoctor:process-asciidocafter the command, you can src/docs/asciidoc/htmlcatalog available to generate the final deployment of static HTML a.

Document preview

It is not bad!

其实这个插件可以生成很多类型的接口文档，markdown类型也可以。大家下来，可以自己研究一下。好了，今天经验就分享到这里了。

来源：站长平台