1. 介绍
介绍如何使用Swagger服务。该项目主要利用Spring Boot的自动化配置特性来实现快速的将Swagger2引入Spring Boot应用来生成API文 档，简化原生使用Swagger的整合代码
1.1. 如何使用
1.1.1. 引入依赖
在bulid.gradle文件中引入依赖jar包：
implementation ("com.spring4all:swagger-spring-boot-starter:2.0.0.RELEASE")
1.1.2. 使用注解
在应用主类中增加@EnableSwagger2Doc注解
@ComponentScan(basePackages = ["org.yunchen.gb.example.demo", "org.yunchen.gb"])
@SpringBootApplication
@Configuration
@EnableSwagger2Doc
class DemoApplication extends SpringBootServletInitializer implements WebApplicationInitializer {
static void main(String[] args) {
SpringApplication.run DemoApplication, args
}
@Override
protected SpringApplicationBuilder configure(SpringApplicationBuilder application) {
return application.sources(DemoApplication.class);
}
}
默认情况下就能产生所有当前Spring MVC加载的请求映射文档。
2. 添加配置
2.1. 在yml文件中更细致的配置内容
swagger.enabled: true swagger.title: project swagger2 doc swagger.description: project swagger2 doc swagger.version: 2.9.2.RELEASE swagger.license: Apache License, Version 2.0 swagger.licenseUrl: https://www.apache.org/licenses/LICENSE-2.0.html swagger.termsOfServiceUrl: http://gb.yunchen.org swagger.contact.name: changeit swagger.contact.url: http://gb.yunchen.org/ swagger.contact.email: demo@yunchen.org swagger.base-package: org.yunchen swagger.base-path: /** swagger.exclude-path: /error # 鉴权策略ID，对应 SecurityReferences ID swagger.authorization.name: Authorization # 鉴权策略，可选 ApiKey | BasicAuth | None，默认ApiKey swagger.authorization.type: ApiKey # 鉴权传递的Header参数 swagger.authorization.key-name: token # 需要开启鉴权URL的正则, 默认^.*$匹配所有URL swagger.authorization.auth-regex: ^.*$
2.2. 配置说明
默认配置 swagger.enabled=是否启用swagger，默认：true swagger.title=标题 swagger.description=描述 swagger.version=版本 swagger.license=许可证 swagger.licenseUrl=许可证URL swagger.termsOfServiceUrl=服务条款URL swagger.contact.name=维护人 swagger.contact.url=维护人URL swagger.contact.email=维护人email swagger.base-package=swagger扫描的基础包，默认：全扫描 swagger.base-path=需要处理的基础URL规则，默认：/** swagger.exclude-path=需要排除的URL规则，默认：空 swagger.host=文档的host信息，默认：空
2.3. 分组配置
当我们一个项目的API非常多的时候，我们希望对API文档实现分组。从1.2.0.RELEASE开始，将支持分组配置功能
2.3.1. 具体配置内容如下：
swagger.docket.<name>.title=标题 swagger.docket.<name>.description=描述 swagger.docket.<name>.version=版本 swagger.docket.<name>.license=许可证 swagger.docket.<name>.licenseUrl=许可证URL swagger.docket.<name>.termsOfServiceUrl=服务条款URL swagger.docket.<name>.contact.name=维护人 swagger.docket.<name>.contact.url=维护人URL swagger.docket.<name>.contact.email=维护人email swagger.docket.<name>.base-package=swagger扫描的基础包，默认：全扫描 swagger.docket.<name>.base-path=需要处理的基础URL规则，默认：/** swagger.docket.<name>.exclude-path=需要排除的URL规则，默认：空 swagger.docket.<name>.name=参数名 swagger.docket.<name>.modelRef=指定参数类型 swagger.docket.<name>.parameterType=指定参数存放位置,可选header,query,path,body.form swagger.docket.<name>.required=true=指定参数是否必传，true,false
说明：<name>为swagger文档的分组名称，同一个项目中可以配置多个分组，用来划分不同的API文档。
2.3.2. 分组配置示例
swagger.docket.aaa.title=group-a swagger.docket.aaa.description=Starter for swagger 2.x swagger.docket.aaa.version=1.3.0.RELEASE swagger.docket.aaa.termsOfServiceUrl=https://gitee.com/didispace/spring-boot-starter-swagger swagger.docket.aaa.contact.name=zhaiyongchao swagger.docket.aaa.contact.url=http://spring4all.com/ swagger.docket.aaa.contact.email=didi@potatomato.club swagger.docket.aaa.excludePath=/ops/** swagger.docket.bbb.title=group-bbb swagger.docket.bbb.basePackage=com.yonghui
说明：默认配置与分组配置可以一起使用。在分组配置中没有配置的内容将使用默认配置替代，所以默认配置可以作为分组配置公共部分属性的配置。swagger.docket.aaa.globalOperationParameters[0].name会覆盖同名的全局配置。
2.4. 自定义全局响应消息配置（1.6.0 + 支持）
支持 POST,GET,PUT,PATCH,DELETE,HEAD,OPTIONS,TRACE 全局响应消息配置，配置如下
// 取消使用默认预定义的响应消息,并使用自定义响应消息 swagger.apply-default-response-messages=false swagger.global-response-message.get[0].code=401 swagger.global-response-message.get[0].message=401get swagger.global-response-message.get[1].code=500 swagger.global-response-message.get[1].message=500get swagger.global-response-message.get[1].modelRef=ERROR swagger.global-response-message.post[0].code=500 swagger.global-response-message.post[0].message=500post swagger.global-response-message.post[0].modelRef=ERROR
3. 一些建议
因为swagger会自动扫描所有的controller文件，而真正需要交互的文档api只有特点的一些controller，建议使用 @ApiIgnore注解屏蔽掉GB系统的controller，如BaseUserController，BaseRoleController,WorkspaceController等等。