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

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", "//www.cnblogs.com/itdragon/", "[email protected]"))
                .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 文档效果图

1585375227962

3. 常用注解介绍

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

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

4. Swagger2文档导出成pdf

4.1 生成pdf的格式

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

接口定义的部分:

1585368750721

实体类声明的部分:

1585369012187

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

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 = "[email protected]"
                name = "ITDragon"
                url = "//www.cnblogs.com/itdragon/"
            }
            license {
                url = "//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文件。

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