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目录下创建 estkotlincomitdragonserverITDragonGenerateDoc.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文件。