SpringBoot 集成Swagger2自动生成文档和导出成静态文件

1. 简介
2. 集成Swagger2
3. 常用注解介绍
4. Swagger2文档导出成pdf
- 4.1 生成pdf的格式
- 4.2 生成静态文档步骤

1. 简介

今天是五一的一天，武汉因为疫情不能随意出去，写篇博客打发时间。今天介绍一款非常热门的API开发工具-----Swagger，其遵循OpenAPI规范。使用简单、可以自动化生成API文档、可以模拟HTTP接口请求等强大的功能。它可以节省我们的开发时间，从而提高工作效率。不仅如此，Swagger还支持生成静态文档的功能，可以用来交付一些对文档要求并不是很高的客户。

2. 集成Swagger2

SpringBoot 集成Swagger也非常简单，同样也是简单的三个步骤：导包、配置和使用。

2.1 导入Swagger库

swaggerVersion = '2.6.1'

compile("io.springfox:springfox-swagger2:${swaggerVersion}")

compile("io.springfox:springfox-swagger-ui:${swaggerVersion}")

这两个是swagger自动生成文档需要的库。若需要生成静态文档，还需要导入其他额外的库。

2.2 配置Swagger基本信息

package com.itdragon.server.config

import org.springframework.context.annotation.Bean

import org.springframework.context.annotation.Configuration

import springfox.documentation.builders.ApiInfoBuilder

import springfox.documentation.builders.PathSelectors

import springfox.documentation.builders.RequestHandlerSelectors

import springfox.documentation.service.ApiInfo

import springfox.documentation.service.Contact

import springfox.documentation.spi.DocumentationType

import springfox.documentation.spring.web.plugins.Docket

import springfox.documentation.swagger2.annotations.EnableSwagger2

@EnableSwagger2

@Configuration

class Swagger2Config {

    @Bean

    fun createRestApi(): Docket {

        return Docket(DocumentationType.SWAGGER_2)  // 指定生成的文档的类型是Swagger2

                .apiInfo(itDragonApiInfo())         // 配置文档页面的基本信息内容

                .select()

                // 指定扫描包路径

                .apis(RequestHandlerSelectors.basePackage("com.itdragon.server.api.rest"))

                .paths(PathSelectors.any())

                .build()

    }

    private fun itDragonApiInfo(): ApiInfo {

        return ApiInfoBuilder()

                .title("ITDragon Swagger API Document")

                .description("ITDragon Swagger Description...")

                .contact(Contact("ITDragon", "https://www.cnblogs.com/itdragon/", "itdragon@qq.com"))

                .version("0.1")

                .description("ITDragon SpringBoot Swagger API INFO")

                .build()

    }

}

1）创建Swagger2的配置类，分别用注解@Configuration和@EnableSwagger2修饰。

2）配置自动生成文档的类型、页面的基本信息和扫描包的路径。

2.3 使用Swagger注解

package com.itdragon.server.api.rest

import io.swagger.annotations.*

import org.springframework.format.annotation.DateTimeFormat

import org.springframework.http.ResponseEntity

import org.springframework.web.bind.annotation.*

import springfox.documentation.annotations.ApiIgnore

import java.util.*

import javax.servlet.http.HttpServletResponse

@Api(tags = ["SwaggerDemo"])

@RestController

@RequestMapping("/itdragon")

class ITDragonSwagger2Controller {

    @ApiOperation("方法说明", notes = "通过ApiOperation注解修饰方法，对方法做详细介绍。若不使用，Swagger会以函数名作为描述。", httpMethod = "GET")

    @GetMapping("/ApiOperation/info")

    fun getITDragonApiOperationInfo(@RequestParam("ids") ids: String): ResponseEntity<Unit> {

        return ResponseEntity.ok(Unit)

    }

    @ApiOperation("参数说明", notes = "通过ApiImplicitParams注解修饰参数，对参数做详细介绍。若不适用，")

    @ApiImplicitParams(value = [

        ApiImplicitParam(name = "deviceIds", value = "设备ID集合，用逗号区分", required = true, dataType = "String", paramType = "query"),

        ApiImplicitParam(name = "search", value = "查询字段")])

    @GetMapping("/ApiImplicitParams/info")

    fun getITDragonApiImplicitParamsInfo(@RequestParam("deviceIds") deviceIds: String,

                                         @RequestParam("search") search: String,

                                         @ApiIgnore currentUser: String): ResponseEntity<Unit> {

        return ResponseEntity.ok(Unit)

    }

    @ApiOperation("对象参数说明", notes = "")

    @PostMapping("/ApiModel/info")

    fun postITDragonApiModelInfo(@RequestBody itDragonCreateInfo: ITDragonCreateInfo) {

    }

    @GetMapping("/Native/info")

    fun getITDragonNativeInfo(@RequestParam("active", required = false) active: Boolean?,

                              @RequestParam("search", required = false) search: String?,

                              @RequestParam("startTime", required = false) @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss") startTime: Date?,

                              @RequestParam("endTime", required = false) @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss") endTime: Date?,

                              @RequestParam("page", required = false, defaultValue = "1") page: Int = 1,

                              @RequestParam("size", required = false, defaultValue = "10") size: Int = 10): ResponseEntity<Unit> {

        return ResponseEntity.ok(Unit)

    }

}

@ApiModel("创建用户模型")

class ITDragonCreateInfo {

    @ApiModelProperty("用户账号,登录账号")

    var username: String? = null

    var nikename: String? = null

}

1）使用注解@Api 修饰类，可以描述这个类的作用。实际使用过程中发现：若用中文描述会存在点不开单个接口详情的问题。

2）使用注解@ApiOperation 修饰方法，可以描述这个方法的功能和注意事项。若不使用则用函数名作为方法功能。

3）使用注解@ApiImplicitParams 修饰方法，可以描述这个方法的参数的作用。若不使用则用参数名作为参数的作用。

4）使用注解@ApiModel 修饰实体类，可以描述这个类的功能。

5）使用注解@ApiModelProperty 修饰实体类的属性，可以描述这个属性的作用。

6）使用注解@ApiIgnore 修饰参数、方法和类，可以在自动生成文档时对修饰的对象进行忽略。

小结：我ITDragon一般在需要有中文描述的场景下会使用这些注解。因为swagger很强大，即便是不使用注解，依然可以自动生成文档。

2.4 文档效果图

3. 常用注解介绍

注解	说明
ApiOperation	描述一个方法的作用和相关的提示信息
ApiImplicitParams	描述一个方法的多个参数的作用、数据类型、等信息
ApiIgnore	生成的文档忽略被修饰的类、方法、参数
ApiModel	描述一个实体类的功能
ApiModelProperty	描述一个实体类属性的作用

还有很多像@Api、@ApiParam、@ApiProperty这些注解，我ITDragon 觉得意义不是特别大。把更多的精力放在业务逻辑上。因为Swagger生成的文档更适合团队内部使用，内部人对文档的要求并不是特别高。但是对于一些严格的客户，文档还是要重新写。

4. Swagger2文档导出成pdf

4.1 生成pdf的格式

我ITDragon 曾经按照网上的教程将swagger文档生成markdown格式的静态文档，然后再通过Typora工具导出成pdf。虽然也支持导出成word文档。但是word文档的排版不好看。而且静态文档的最大缺陷就是实体类和接口是分开的。效果图如下所示。

接口定义的部分：

实体类声明的部分：

当然你也可以把实体类的数据拷贝到接口对应的位置。但是这个工作量也不小。

4.2 生成静态文档步骤

4.2.1 配置gradle

完整代码可以点击文章底部的链接地址

buildscript {

    ext {

        springBootVersion = '2.0.6.RELEASE'

        swaggerVersion = '2.6.1'

    }

    dependencies {

        classpath("org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}")

        classpath("com.benjaminsproule:swagger-gradle-plugin:1.0.7")

    }

}

apply plugin: 'com.benjaminsproule.swagger'

swagger {

    apiSource {

        springmvc = true

        locations = ["com.itdragon.server.api.rest"]

        schemes = ["http", "https"]

        host = "www.cnblogs.com/itdragon"

        info {

            title = "ITDragon Swagger2 API Document"

            version = "0.1"

            description = "API Document Description"

            contact {

                email = "itdragon@qq.com"

                name = "ITDragon"

                url = "https://www.cnblogs.com/itdragon/"

            }

            license {

                url = "http://www.apache.org/licenses/LICENSE-2.0.html"

                name = "Apache 2.0"

            }

        }

        outputPath = "${project.rootDir}/generated/document.html"

        swaggerDirectory = "${project.rootDir}/generated/swagger-ui"

        attachSwaggerArtifact = true

    }

}

dependencies {

    /* swagger */

    compile("io.swagger:swagger-annotations:1.5.21")

    compile("io.springfox:springfox-swagger2:${swaggerVersion}")

    compile("io.springfox:springfox-swagger-ui:${swaggerVersion}")

    compile("io.springfox:springfox-staticdocs:${swaggerVersion}")

    testCompile('org.springframework.restdocs:spring-restdocs-mockmvc:2.0.2.RELEASE')

}

4.2.2 生成swagger json文件

在项目根目录下，运行./gradlew generateSwaggerDocumentation 命令。

若成功，会在根目录下生成：/generated/swagger-ui/swagger.json，且这个json文件内容不为空。反之则失败。

admin@DESKTOP-3 MINGW64 /d/daydayup/SpringBoot/spring-boot-swagger2 (master)

$ ./gradlew generateSwaggerDocumentation

> Task :compileKotlin UP-TO-DATE

> Task :compileJava NO-SOURCE

> Task :processResources UP-TO-DATE

> Task :classes UP-TO-DATE

> Task :generateSwaggerDocumentation

BUILD SUCCESSFUL in 5s

3 actionable tasks: 1 executed, 2 up-to-date

注意：

1）若ApiImplicitParam 若没有dataType或者paramType，则会导致生成静态文档报错> Unrecognized Type: [null]

4.2.3 生成swagger markdown文件

在src目录下创建\test\kotlin\com\itdragon\server\ITDragonGenerateDoc.kt 文件，代码内容如下：

package com.itdragon.server

import io.github.robwin.markup.builder.MarkupLanguage

import io.github.robwin.swagger2markup.Swagger2MarkupConverter

import org.junit.Test

class ITDragonGenerateDoc {

    private val snippetDir = "/generated/snippets"

    private val outputDir = "generated/swagger-ui"

    /**

     * 第一步：./gradlew generateSwaggerDocumentation

     * 第二步：./gradlew test --tests *ITDragonGenerateDoc

     */

    @Test

    @Throws(Exception::class)

    fun doIt() {

        Swagger2MarkupConverter.from("$outputDir/swagger.json")

                .withMarkupLanguage(MarkupLanguage.MARKDOWN)

                .withExamples(snippetDir)

                .build()

                .intoFolder(outputDir)

    }

}

同时在项目根目录下运行./gradlew test --tests *ITDragonGenerateDoc 命令。

运行成功后会在/generated/swagger-ui/目录下生成三个文件，分别是：overview.md、definitions.md、paths.md文件。

注意：

1）若指定 .withPathsGroupedBy(GroupBy.TAGS) 按照按tag排序，但是有的注解并没有指定tag会报错。

4.2.4 markdown转pdf

我们可以使用Typora工具，将markdown格式的文件导出成pdf或者word文件。

源码地址：https://github.com/ITDragonBlog/daydayup