SpringBoot2中，怎么生成静态文档

【推荐】2019 Java 开发者跳槽指南.pdf(吐血整理) >>>

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

预览一下文档