前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新。接口文档对于程序员来说,就跟注释一样,经常会抱怨别人写的代码没有写注释,然而自己写起代码起来,最讨厌的,也是写注释。所以仅仅只通过强制来规范大家是不够的,随着时间推移,版本迭代,接口文档往往很容易就跟不上代码了。
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化的 Web 服务。其主要作用如下:
在项目的 build.gradle 文件中。在“dependencies”节点增加 Swagger 依赖;
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// RESTful API 文档生成工具
// https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui
compile group: "io.springfox", name: "springfox-swagger-ui", version: SWAGGER_VERSION
compile group: "io.springfox", name: "springfox-swagger2", version: SWAGGER_VERSION
一般情况下将 Swagger 的配置类与SpringBoot 的应用类放在同一个package ,比如“cn.sagacloud.server.datacenter”。 创建 Swagger 配置文件 Swagger2Config.kt文件。
/*
* ********************************************************************************************************************
*
* :*$@@%$*: ;: ;; ;;
* :@@%! :!@@%: %! ;%%@@%$ =@@@@@@@%; @%@@@%%%%@@@@@
* :@%; :$= %%$$$%$$ ;$$ ;$@= !@$
* =@! %! @ $=;% !@@@%: !$$$$$$$$$$$$$$=
* =@* %! @ $= % %@= =%@! %=
* *$%%! @@= ;=$%%%$*: %! @ $= % =%%%%%%@$ *%: =%
* %@@!: !@@@%=$@@@@%! :*@@$: %! @ $= % $* ;@ @* :%*
* ;@@! ;!!!;: ;@%: =======@%========* @ $$ % $%*****$@ :@$=*********=@$
* $@* ;@@@%=!: *@*
* =@$ ;;;!=%@@@@=! =@!
* %@$: =@%: :*@@@* %@= Copyright (c) 2016-2019. 北京上格云技术有限公司
* ;%@@$=$@@%* *@@@$=%@@%;
* ::;:: ::;:: All rights reserved.
*
* ********************************************************************************************************************
*/
package cn.sagacloud.server.datacenter
import org.slf4j.LoggerFactory
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import springfox.documentation.builders.ApiInfoBuilder
import springfox.documentation.builders.ParameterBuilder
import springfox.documentation.builders.PathSelectors
import springfox.documentation.builders.RequestHandlerSelectors
import springfox.documentation.schema.ModelRef
import springfox.documentation.service.ApiInfo
import springfox.documentation.service.Contact
import springfox.documentation.service.Parameter
import springfox.documentation.spi.DocumentationType
import springfox.documentation.spring.web.plugins.Docket
import springfox.documentation.swagger2.annotations.EnableSwagger2
/**
* RESTful API文档生成器Swagger2配置
*
* @author PLX
*/
@Configuration
@EnableSwagger2
open class Swagger2Config {
companion object {
// 日志
private val logger = LoggerFactory.getLogger(Swagger2Config::class.java)
} // Companion object
/**
* 创建RestApi文档生成器
*
* @return 返回文档生成器对象
*/
@Bean
open fun createRestApi(): Docket {
logger.debug("createRestApi")
val builder = ParameterBuilder()
val builderComming = ParameterBuilder()
val builderPhone = ParameterBuilder()
val pars = ArrayList<Parameter>()
builder.name("ProjectId").description("项目ID").modelRef(ModelRef("string")).parameterType("header").required(false).build()
builderComming.name("Coming").description("来源").modelRef(ModelRef("string")).parameterType("header").required(false).build()
builderPhone.name("Account").description("账号信息").modelRef(ModelRef("string")).parameterType("header").required(false).build()
pars.add(builder.build())
pars.add(builderComming.build())
pars.add(builderPhone.build())
return Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("cn.sagacloud.server"))
.paths(PathSelectors.any())
.build()
.globalOperationParameters(pars)
} // Function createRestApi()
/**
* 返回API信息基本
*
* @return 返回Api基本信息
*/
private fun apiInfo(): ApiInfo {
return ApiInfoBuilder()
.title("数据中心API")
.description("接口中Comming来源信息:扫楼:App-scanBuildingApp、慧运营运维平台:adm、Revit算法:RevitAlgorithm")
.termsOfServiceUrl("http://www.sagacloud.cn/")
.contact(Contact("张维新", "", "zhangweixin@sagacloud.cn"))
.version("2.0")
.build()
} // Function apiInfo()
} // Class Swagger2Config