SpringBoot快速集成swagger文檔

1. 簡介

該框架基於swagger2-2.9.2與SpringBoot-2.0.1版本進行搭建,兼容SpringBoot2.x以上版本,不兼容1.x版本,maven依賴以下:java

<dependency>
		<groupId>io.github.wilson-he</groupId>
		<artifactId>swagger2-spring-boot-starter</artifactId>
		<version>1.1.0</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
    - 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...)
    - security-contexts
      - path-selectors
      - method-selectors
      - security-references
        
        reference
        
        scopes
    - security-schemes
      - 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
2.2 詳解
標註了extra的皆爲我的開發配置，非根據swagger原有配置轉換而來，該簡介主要對extra部分進行講解。
- swagger.print-init:是否在控制檯輸出各docket初始化的配置信息
- swagger.enabled:是否開啓swagger自動化配置(不設置則默認初始化swagger docket)
- swagger.profiles:指定profile環境下才進行文檔生成
- swagger.dockets:用於配置多個docket，Map類型，key爲當前docket在Spring中的bean name,value屬性配置同docket,同時配置swagger.docket將一塊兒生效
- 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信息

3. 快速開始

啓動類Application.javagit

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
@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.ymlgithub

swagger:
  print-init: true #非必需,默認true
  enabled: true #非必需,默認true
  docket:
    base-package: org.noslim.web   #必需
server:
  port: 8888   #非必需
  servlet:
    context-path: /test  #非必需

運行效果圖: web

SpringBoot快速集成swagger文檔

1. 簡介

2. 配置

2.1 結構

2.2 詳解

3. 快速開始

更多使用姿式請參考文檔