SpringBoot2中，怎么生成静态文档

提示：扫一扫查出行
【扫一扫了解最新限行尾号】
复制提示

在实际开发过程中，我们通过swagger就可以生成我们的接口文档，这个文档就可以提供给前端人员开发使用的。但是，有时候，我们需要把我们的接口文档，提供给第三方合作公司怎么办？

本人现在就遇到这个问题。我们的项目开发完成之后，也是前后端分离的模式。但是，第三方公司需要我们的接口文档，怎么办？那就需要我们把swagger的文档，生成静态文档才可以发送过去。

接口文档

说起来接口文档，大家最熟悉的就是swaggger了吧。这个可以很方便的可以注解的方式，就可以生成我们需要的文档。而且可以在线调试接口。

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

上面就是项目启动之后，swagger给我们提供的可视化界面了。

swagger项目集成

springboot中集成swagger很简单，只需要我们导入依赖，然后在方法上写上注解就可以了。

应用主类中添加@EnableSwagger2Doc注解，具体如下

根据项目需要，我们可以修改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=/**

启动应用，访问：http://localhost:8080/swagger-ui.html 接可以访问了

注解很简单

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

简单的接口文档就部署完了，接下来就是静态化了

接口文档静态化

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

今天用到的就是Swagger2Markup，这个插件就可以帮助我们来实现静态化功能。

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

添加依赖

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

这个时候，我们<scope>test</scope>，这个就可以在正式环境中去掉这个依赖了。

为了大家直观，编写一个测试类来完成这个静态化。

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

执行完这个代码之后，就可以在项目目录下生产我们需要的 ASCIIDOC 文档了

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

生成HTML

我们大都是需要的就是html文档，方便查看。接下来，只需要修改一点配置就可以了。

添加插件依赖

<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>这个代码就可以生成html文档了。

执行该插件的asciidoctor:process-asciidoc命令之后，就能src/docs/asciidoc/html目录下生成最终可用的静态部署HTML了。

预览一下文档