SpringBoot整合swagger2生成接口文档，并且实现导出功能

写在前言：前阵子工作涉及到与其他公司进行接口对接，要求要swagger文档，之前没有用过这个，于是写了一下，整理出来

1、添加swagger依赖

在项目的pom文件中添加swagger的依赖

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

2、编写swagger的配置类

代码如下

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包路径
                .apis(RequestHandlerSelectors.basePackage("com.anso.data.sync.api.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("接口文档")
                //创建人
                .contact(new Contact("yedan", null, null))
                //版本号
                .version("1.0")
                //描述
                .description("数据对接接口文档")
                .build();
    }
}

3、swagger在接口上的使用，找到需要生成接口文档的controller下，对class直接注解@Api("文件说明")，在对应的接口上直接用注解@ApiOperation("系统主动推送数据")标明方法的作用，对于需要传参的接口可以使用注解@ApiImplicitParam来对参数进行说明，例如：

当有多个参数的时候，可以使用注解@ApiImplicitParams
以上是swagger的使用方式，运行项目可以直接访问 http://localhost:8028/swagger-ui.html，就可以看到对应的接口文档

4、可以在页面上查看swagger文档后，我们可以继续配置能够导出接口文档，导出html文件的方式，直接在项目的pom文件下添加

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.6</version>
    <configuration>
        <!-- asciidoc文档输入路径 -->
        <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
        <!-- html文档输出路径 -->
        <outputDirectory>src/docs/asciidoc/html</outputDirectory>
        <backend>html</backend>
        <sourceHighlighter>coderay</sourceHighlighter>
        <!-- html文档格式参数 -->
        <attributes>
            <doctype>book</doctype>
            <toc>left</toc>
            <toclevels>3</toclevels>
            <numbered></numbered>
            <hardbreaks></hardbreaks>
            <sectlinks></sectlinks>
            <sectanchors></sectanchors>
        </attributes>
    </configuration>
</plugin>

pom文件修改完成后，运行项目，在控制台输入mvn asciidoctor:process-asciidoc 执行，即可在src下可以看到生成的接口文档

5、同理，用同样的方法可以生成MD格式的，修改pom文件

<plugin>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>1.3.1</version>
    <configuration>
        <!-- api-docs访问url -->
        <swaggerInput>http://localhost:8028/v2/api-docs</swaggerInput>
        <!-- 生成为单个文档，输出路径 -->
        <outputFile>src/docs/asciidoc/generated/all</outputFile>
        <config>
            <!-- ascii格式文档 -->
            <swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage>
            <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
        </config>
    </configuration>
</plugin>

pom文件修改完成后，运行项目，在控制台输入mvn swagger2markup:convertSwagger2markup 执行，即可在src下可以看到生成的接口文档
以上就是swagger2生成接口文档的例子