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

预览一下文档

是不是还不错！

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

来源：站长平台