SpringBoot2中，怎么生成静态文档

不念不忘少年蓝@ 2023-06-28 06:20 4阅读 0赞

### SpringBoot2中，怎么生成静态文档 ###

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

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

#### 接口文档 ####

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

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

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI5OTk4MDAz_size_16_color_FFFFFF_t_70][]

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

#### swagger项目集成 ####

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

![20200107202105236.png][]

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

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI5OTk4MDAz_size_16_color_FFFFFF_t_70 1][]

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

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

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

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

html 这个代码就可以生成html文档了。

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

预览一下文档

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI5OTk4MDAz_size_16_color_FFFFFF_t_70 2][]

是不是还不错！

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

#### 以上内容皆为本人观点，欢迎大家提出批评和指导，我们一起探讨！ ####

![20200107202105689.png][]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI5OTk4MDAz_size_16_color_FFFFFF_t_70]: https://img-blog.csdnimg.cn/20200107202111935.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI5OTk4MDAz,size_16,color_FFFFFF,t_70
[20200107202105236.png]: https://img-blog.csdnimg.cn/20200107202105236.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI5OTk4MDAz_size_16_color_FFFFFF_t_70 1]: https://img-blog.csdnimg.cn/20200107202112325.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI5OTk4MDAz,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI5OTk4MDAz_size_16_color_FFFFFF_t_70 2]: https://img-blog.csdnimg.cn/20200107202112610.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI5OTk4MDAz,size_16,color_FFFFFF,t_70
[20200107202105689.png]: https://img-blog.csdnimg.cn/20200107202105689.png