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
  - 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…)
  - 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.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)查看配置，如下图:
返回码配置example
在这里插入图片描述