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