目录
1. 简介
2. 集成 Swagger2
2.1 导入 Swagger 库
2.2 配置 Swagger 基本信息
2.3 使用 Swagger 注解
2.4 文档效果图
3. 常用注解介绍
4. Swagger2 文档导出成 PDF
4.1 生成 PDF 的格式
4.2 生成静态文档步骤
4.2.1 配置 gradle
4.2.2 生成 swagger JSON 文件
4.2.3 生成 swagger Markdown 文件
4.2.4 Markdown 转 PDF
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
来源: https://www.cnblogs.com/itdragon/p/12588010.html