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. 快速开始

更多使用姿式请参考文档