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 文档效果图

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 = "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

posted @ 2020-05-01 16:58 ITDragon龙阅读(15301) 评论(0) 编辑收藏举报

刷新页面返回顶部

ITDragon龙

每天都在进步，每周都在总结，架构师的修罗之路。更多文章可访问：http://blog.csdn.net/qq_19558705

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

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

公告

ITDragon龙

每天都在进步，每周都在总结，架构师的修罗之路 。 更多文章可访问：http://blog.csdn.net/qq_19558705

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

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

公告

每天都在进步，每周都在总结，架构师的修罗之路。更多文章可访问：http://blog.csdn.net/qq_19558705