swagger2-spring-boot-starter自動化配置框架使用簡介
阿新 • • 發佈：2018-11-19
swagger2-spring-boot-starter整合框架使用簡介
簡介
該框架基於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.0-RELEASE</version> </dependency>
配置結構
為了讓使用者更清晰的瞭解swagger各層次配置，該框架主要根據原swagger配置結構進行屬性分層配置，結構樹如下：
- swagger
- print-init(extra)
- 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(required,null將導致NPE)
- 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
配置簡介
標註了extra的皆為個人開發配置，非根據swagger原有配置轉換而來，該簡介主要對extra部分進行講解。
- swagger.print-init:是否在控制檯輸出各docket初始化的配置資訊
- swagger.enabled:是否開啟swagger自動化配置(為了保留之前的配置但不開啟配置而添加了該配置項)
- swagger.dockets:用於配置多個docket，屬性配置同docket,同時配置swagger.docket將一起生效，base-package須填，否則將報NullPointException，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資訊
快速開始
啟動類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 #必需
docket:
base-package: org.noslim.web #必需
server:
port: 8888 #非必需
servlet:
context-path: /test #非必需
執行效果圖:
多文件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: [email protected]
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: [email protected]
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: [email protected]
url: http://blog.csdn.net/z28126308/
base-package: org.noslim.controller
group-name: 訂單模組
swagger-ui
配置提示
基本上非集合配置都提供了自動填充提示功能，效果圖如下:
yml無法為集合如List、Map提供提示，如該框架中的parameters(List)、dockets(Map)，個人建議可以直接配置paramter、docket再copy到parameters、dockets下，某些沒有單數配置的如response-messages、api-key-list可以在IDE選中該配置然後快捷鍵提示(Ctrl+Q)檢視配置，如下圖:
結語
各位在使用該框架遇到bug時希望可以給我留個反饋，要是有不錯的idea也可以留個言，
要是覺得用起來不錯的可以點個贊和去github收藏下(https://github.com/Wilson-He/swagger2-spring-boot-starter)