SpringMVC集成swagger2 及导出API文档

一、导入maven依赖

<!--swagger2- start ->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.4.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.4.0</version>
</dependency>
<!--swagger2- end ->
<!--  swagger导出PDF/HTML所需依赖 START-->
<dependency>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup</artifactId>
    <version>1.3.1</version>
</dependency>
<!-- swagger导出PDF/HTML所需依赖 END -->

二、编写Swagger2配置类

package com.project.commons.annotation;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @ClassName Swagger2Config.java
 * @version 1.0.0
 * @Description TODO
 * @createTime 2019-11-28 14:59:00
 */

@Configuration
@EnableWebMvc
@EnableSwagger2
@ComponentScan(basePackages = {"com.project.api"})
public class Swagger2Config extends WebMvcConfigurationSupport {


 @Bean
 public Docket buildDocket() {
  return  new Docket(DocumentationType.SWAGGER_2)
          .apiInfo(apiInfo())
          .select()
          .apis(RequestHandlerSelectors.basePackage("com.project.api")) /**此处配置包含接口的包**/
          .paths(PathSelectors.any())
          .build();

 }

/**
展示页显示信息
**/
 public ApiInfo apiInfo() {
  return  new ApiInfoBuilder()
          .title("Welcome to Swagger API Platform !")
          .description("api调试页面")
          .termsOfServiceUrl("http://localhost:8080/project/swagger-ui.html")
          .contact("aaronmer")
          .version("0.0.1")
          .build();

 }
}

三、配置Swagger2Config初始化的bean以及配置资源映射目录

<!--在Spring-MVC.xml中添加如下内容-->

<!--Swagger2Config 初始化-->
<bean class="com.project.commons.annotation.Swagger2Config"></bean>
<!-- 配置不同的location，就可以在生产环境中禁用Swagger2 -->
<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>

四、启动项目查看接口文档

访问地址：http://localhost:8080/project/swagger-ui.html

这步根据自己的项目访问路径访问，其实是访问项目路径（project）下的swagger-ui.html

这时可以查看如下的页面，如果要登录的话先登录自己的系统

这时我们看到的都是基本的类型，无法得知具体描述，如果想要有更好的可读性请详细了解下面的这些注解，本教程只涉及引入及文档导出，此处对进一步的完善不作深入探讨

1. @Api：修饰整个类，描述 Controller 的作用
2. @ApiOperation：描述一个类的一个方法，或者说一个接口
3. @ApiParam：单个参数描述
4. @ApiModel：用对象来接收参数
5. @ApiProperty：用对象接收参数时，描述对象的一个字段
6. @ApiResponse：HTTP 响应其中 1 个描述
7. @ApiResponses：HTTP 响应整体描述
8. @ApiIgnore：使用该注解忽略这个API
9. @ApiError：发生错误返回的信息
10. @ApiImplicitParam：一个请求参数
11. @ApiImplicitParams：多个请求参数

五、配置pom.xml生成asciidoc文件

AsciiDoc 是一种文本文档格式（轻量级的标记语言），用于编写注释、文档、文章、书籍、电子书、幻灯片、网页、手册页和博客。AsciiDoc 文件可以翻译成多种格式，包括 HTML、PDF、EPUB、手册页面等。AsciiDoc 是高度可配置的，用户可以定制和扩展 AsciiDoc 源文件语法和后端输出标记（几乎可以是任何类型的 SGML/XML 标记）。

这步的目的是生成asciidoc文件，方便进一步转化为html或pdf

这里我们可以自己配置asciidoc文件的生成路径或文件（可以选择输出为单个或多个文件），我这里选择了生成单个文件target/doc/source/api,执行命令后会自动添加后缀

api-docs访问url其实是自己的项目目录下的/v2/api-docs,注意把project改为自己的项目路径

    <!-- mvn asciidoctor:process-asciidoc -->
            <plugin>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>1.3.1</version>
                <configuration>
                    <!-- api-docs访问url -->
                    <swaggerInput>http://localhost:8080/project/v2/api-docs</swaggerInput>
                    <!-- 生成为单个文档，输出路径, 此处的api为文件名-->
                    <outputFile>target/doc/source/api</outputFile>
                    <!-- 生成为多个文档，输出路径
                    <outputDir>target/doc/source/</outputDir>  -->
                    <config>
                        <!-- wiki格式文档 -->
                        <!--<swagger2markup.markupLanguage>CONFLUENCE_MARKUP</swagger2markup.markupLanguage> -->
                        <!-- ascii格式文档 -->
                        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                        <!-- markdown格式文档 -->
                        <!--<swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage>-->
                        <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
                    </config>
                </configuration>
            </plugin>

六、生成asciidoc文件

首先确认项目已经启动，然后在项目目录下执行下面的命令
 

mvn swagger2markup:convertSwagger2markup

生成的asciidoc文件位于项目目录下的target/doc/source/下

七、使用asciidoctor把asciidoc文件转为html或pdf文件

在pom.xml添加如下内容

  <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.3</version>
                <!-- Include Asciidoctor PDF for pdf generation -->
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>1.5.0-alpha.10.1</version>
                    </dependency>
                    <dependency>
                        <groupId>org.jruby</groupId>
                        <artifactId>jruby-complete</artifactId>
                        <version>1.7.21</version>
                    </dependency>
                </dependencies>
                <!-- Configure generic document generation settings -->
                <configuration>
                    <sourceDirectory>target/doc/source/</sourceDirectory>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <attributes>
                        <toc>left</toc>
                    </attributes>
                </configuration>
                <!-- Since each execution can only handle one backend, run
                     separate executions for each desired output type -->
                <executions>
                    <execution>
                        <id>output-html</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>html5</backend>
                            <outputDirectory>target/doc/api/</outputDirectory>
                        </configuration>
                    </execution>

                    <execution>
                        <id>output-pdf</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>pdf</backend>
                            <outputDirectory>target/doc/api/</outputDirectory>
                        </configuration>
                    </execution>

                </executions>
            </plugin>

        </plugins>

在项目根目录执行下面的命令

mvn generate-resources

可以在target/doc/api/下看到生成的html和pdf文件

至此我们可以在平台下直接查看api详情，也可以导出接口文档查看