项目简介

该项目主要利用Spring Boot的自动化配置特性来实现快速的将swagger2引入spring boot应用来生成API文档,简化原生使用swagger2的整合代码。

GitHub:https://github.com/dyc87112/s...
码云:http://git.oschina.net/didisp...
博客:http://blog.didispace.com

小工具一枚,欢迎使用和Star支持,如使用过程中碰到问题,可以提出Issue,我会尽力完善该Starter

版本基础

  • Spring Boot:1.5.x

  • Swagger:2.7.x

如何使用

在该项目的帮助下,我们的Spring Boot可以轻松的引入swagger2,主需要做下面两个步骤:

  • pom.xml中引入依赖:

<dependency>
    <groupId>com.didispace</groupId>
    <artifactId>spring-boot-starter-swagger</artifactId>
    <version>1.1.0.RELEASE</version>
</dependency>
  • 在应用主类中增加@EnableSwagger2Doc注解

@EnableSwagger2Doc
@SpringBootApplication
public class Bootstrap {

    public static void main(String[] args) {
        SpringApplication.run(Bootstrap.class, args);
    }

}

默认情况下就能产生所有当前Spring MVC加载的请求映射文档。

参数配置

更细致的配置内容参考如下:

配置示例

swagger.title=spring-boot-starter-swagger
swagger.description=Starter for swagger 2.x
swagger.version=1.1.0.RELEASE
swagger.license=Apache License, Version 2.0
swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html
swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger
swagger.contact.name=程序猿DD
swagger.contact.url=http://blog.didispace.com
swagger.contact.email=dyc87112@qq.com
swagger.base-package=com.didispace
swagger.base-path=/**
swagger.exclude-path=/error, /ops/**

配置说明

  • swagger.title=标题

  • swagger.description=描述

  • swagger.version=版本

  • swagger.license=许可证

  • swagger.licenseUrl=许可证URL

  • swagger.termsOfServiceUrl=服务条款URL

  • swagger.contact.name=维护人

  • swagger.contact.url=维护人URL

  • swagger.contact.email=维护人email

  • swagger.base-package=swagger扫描的基础包,默认:全扫描

  • swagger.base-path=需要处理的基础URL规则,默认:/**

  • swagger.exclude-path=需要排除的URL规则,默认:空

Path规则说明

swagger.base-pathswagger.exclude-path使用ANT规则配置。

我们可以使用swagger.base-path来指定所有需要生成文档的请求路径基础规则,然后再利用swagger.exclude-path来剔除部分我们不需要的。

比如,通常我们可以这样设置:

management.context-path=/ops

swagger.base-path=/**
swagger.exclude-path=/ops/**, /error

上面的设置将解析所有除了/ops/开始以及spring boot自带/error请求路径。

其中,exclude-path可以配合management.context-path=/ops设置的spring boot actuator的context-path来排除所有监控端点。

homesangsang · 9月26日

请问,我在使用的时候弹出了如下内容:Unable to infer base url. This is common when using dynamic servlet registration or when the API is behind an API Gateway. The base url is the root of where all the swagger resources are served. For e.g. if the api is available at http://example.org/api/v2/api... then the base url is http://example.org/api/. Please enter the location manually:
这是因为什么?我在没用这个之前,swagger也是空白页

+1 回复

mercyblitz · 8月14日

star

回复

载入中...
程序员DD 程序员DD

192 声望