1. 简介
该框架是个人为了提高swagger的配置效率对swagger特性与SpringBoot进行了集成，基于swagger2-2.9.2与SpringBoot-2.0.1版本进行搭建,兼容SpringBoot2.x以上版本,不兼容1.x版本,maven依赖如下:
<dependency>
<groupId>io.github.wilson-he</groupId>
<artifactId>swagger2-spring-boot-starter</artifactId>
<version>1.0.4</version>
</dependency>
2. 配置
-
2.1 结构
为了让使用者更清晰的了解swagger各层次配置，该框架主要根据原swagger配置结构进行属性分层配置，结构树如下：- swagger
- print-init(extra)
- profiles
- enabled(extra)
- security-configuration
- properties(client-id,client-secret,scope-separator...)
- dockets(extra)
- docket-bean-A
- docket.properties
- docket-bean-B
- docket.properties
- ...
- docket-bean-A
- docket
- base-package
- path-mapping
- group-name
- host
- protocols
- consumers
- produces
- direct-model-substitutes
- api-info
- contact
- properties(name,email,url)
- properties(version,title.description,license...)
- contact
- security-contexts
- path-selectors
- method-selectors
- security-references
- reference
- scopes
- security-schemas
- api-key-list
- basic-auth-list
- oauth-list
- path-selectors
- include-patterns(extra)
- exclude-patterns(extra)
- global-parameter(extra)
- global-parameters
- - global-parameter[a].properties
- - global-parameter[b].properties
- response-message-language(extra)
- response-messages
- resources-provider(配置网关路由文档,需额外开启enable,可参考zuul配置-百度例子)
- swagger-resources
- name
- url
- swagger-version
- swagger-resources
- swagger
-
2.2 详解
标注了extra的皆为个人开发配置，非根据swagger原有配置转换而来，该简介主要对extra部分进行讲解。-
swagger.print-init:是否在控制台输出各docket初始化的配置信息
输出初始化信息 - swagger.enabled:是否开启swagger自动化配置(不设置则默认初始化swagger docket)
- swagger.profiles:指定profile环境下才进行文档生成
- swagger.dockets:用于配置多个docket，属性配置同docket,同时配置swagger.docket将一起生效，example:
- swagger:
dockets:
docket-test: #注册一个beanName为docket-test的Docket到Spring容器中
base-package: org.noslim.controller.test
docket-order: #注册一个beanName为docket-order的Docket到Spring容器中
base-package: org.noslim.controller.order
- swagger:
- swagger.docket.path-selectors:swagger-ui上的路径选择器
- include-patterns:路径显示样式
- exclude-patterns:路径隐藏样式
- swagger.docket.global-parameter:配置全局参数,若同时配置了global-parameters,global-parameters会将global-parameter也加到全局参数里
-
swagger.docket.response-message-language:全局信息返回语言(cn,en)，下图为cn信息
language: en信息图
-
3. 快速开始
启动类Application.java
package org.noslim.web;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@SpringBootApplication
@RestController
@Api
@ApiResponses({@ApiResponse(code = 200, message = "success", response = ResponseEntity.class)})
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class);
}
@GetMapping("/index")
public String index() {
return "index";
}
@GetMapping("/home")
public String home() {
return "home";
}
@GetMapping("/home/test")
public String homeTest() {
return "test";
}
@GetMapping("/test")
public String test() {
return "test";
}
@GetMapping("/index/test")
public String indexTest() {
return "test";
}
@GetMapping("/index/test/a")
public String indexTestA() {
return "test";
}
}
application.yml
swagger:
print-init: true #非必需,默认false
enabled: true 非必需,默认true
docket:
base-package: org.noslim.web #必需
server:
port: 8888 #非必需
servlet:
context-path: /test #非必需
运行效果图:
控制台打印信息
4. 多文档Docket配置yml-demo
-
application.yml
swagger: print-init: true enabled: true security-configuration: client-id: client-1 client-secret: secretA scope-separator: \, use-basic-authentication-with-access-code-grant: true docket: base-package: org.noslim.web group-name: origin direct-model-substitutes: [java.sql.Timestamp,java.lang.Long] path-selectors: include-patterns: [/home/*,/**] exclude-patterns: [/index/*] api-info: contact: name: Wilson email: 845023508@qq.com url: http://blog.csdn.net/z28126308/ security-contexts: path-selectors: [/**] method-selectors: [get,post,put,delete] security-references: scopes: scopeA: manage scope A scopeB: manage scope B reference: reference-1 security-schemas: basic-auth-list: [basic-1,basic-2] api-key-list: - name: query key-name: Authorization pass-as: header # oauth-list: # - name: oa1 # grant-types: [admin] # scopes: # scopeA: manage scope A response-message-language: cn response-messages: - code: 501 message: 测试信息 global-parameters: - name: sss param-type: header description: 全局header sss dockets: docket-test: base-package: org.noslim.web.test group-name: 测试模块 api-info: contact: name: Wilson email: 845023508@qq.com url: http://blog.csdn.net/z28126308/ response-messages: - code: 501 message: 测试 global-parameters: - name: token description: 令牌 param-type: header - name: userId description: 用户id param-type: query docket-order: api-info: contact: name: Wilson email: 845023508@qq.com url: http://blog.csdn.net/z28126308/ base-package: org.noslim.controller group-name: 订单模块 -
swagger-ui效果图
在这里插入图片描述
5. 配置提示
基本上非集合配置都提供了自动填充提示功能，效果图如下:
在这里插入图片描述
在这里插入图片描述
yml无法为集合如List、Map提供提示，如该框架中的parameters(List)、dockets(Map)，个人建议可以直接配置paramter、docket再copy到parameters、dockets下，某些没有单数配置的如response-messages、api-key-list可以在IDE选中该配置然后快捷键提示(Ctrl+Q)查看配置，如下图:
返回码配置example
在这里插入图片描述
在这里插入图片描述
6. zuul配置例子
-
application.yml
server: port: 8999 spring: application: name: api-docs zuul: routes: user-provider: path: /user-provider/** user-consumer: path: /user-consumer/** eureka: client: service-url: defaultZone: http://eureka1:50001/eureka/,http://eureka2:50002/eureka/ swagger: resources-provider: swagger-resources: - name: 用户消费者模块 url: /user-consumer/v2/api-docs - name: 用户提供者模块 url: /user-provider/v2/api-docs enabled: true -
效果图
zuul swagger-ui
