swagger2-spring-boot-starter自动化配置框架使用

1. 简介

该框架是个人为了提高swagger的配置效率对swagger特性与SpringBoot进行了集成，基于swagger2-2.9.2与SpringBoot-2.0.1版本进行搭建,兼容SpringBoot2.x以上版本,不兼容1.x版本,maven依赖如下:

    
        io.github.wilson-he
        swagger2-spring-boot-starter
        1.0.4
    

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-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

• 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.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: [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效果图

  在这里插入图片描述

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

附源码地址

• 码云
• github
  觉得好用的可以收藏下.