spring-boot-starter-swagger迎新伙伴支持，加速更新进度（1.3.0.RELEASE）

从该starter创建至今收到了不少使用反馈，同时也有不错的童鞋申请加入一起维护。本篇先欢迎小火童鞋的加入及贡献，接下来具体说说本次的更新内容。

本次更新主要新增了下面两项内容：

• 新增API文档的host配置 swagger.host

• 新增对JSR-303注解的支持

同时我们也更新了使用文档，其中涵盖了1.3.0.RELEASE所有支持的配置功能。

更多关于starter的介绍可见如下内容。

简介

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

• 源码地址

• GitHub：https://github.com/dyc87112/spring-boot-starter-swagger

• 码云：https://gitee.com/didispace/spring-boot-starter-swagger

• 使用样例：https://github.com/dyc87112/swagger-starter-demo

• 我的博客：http://blog.didispace.com

• 我们社区：http://spring4all.com

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

版本基础

• Spring Boot：1.5.x

• Swagger：2.7.x

如何使用

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

• 在 pom.xml中引入依赖：

1. <dependency>

2.    <groupId>com.didispace</groupId>

3.    <artifactId>spring-boot-starter-swagger</artifactId>

4.    <version>1.3.0.RELEASE</version>

5. </dependency>

• 在应用主类中增加 @EnableSwagger2Doc注解

1. @EnableSwagger2Doc

2. @SpringBootApplication

3. public class Bootstrap {

4.    public static void main(String[] args) {

5.        SpringApplication.run(Bootstrap.class, args);

6.    }

7. }

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

参数配置

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

配置示例

1. swagger.title=spring-boot-starter-swagger

2. swagger.description=Starter for swagger 2.x

3. swagger.version=1.3.0.RELEASE

4. swagger.license=Apache License, Version 2.0

5. swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html

6. swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger

7. swagger.contact.name=didi

8. swagger.contact.url=http://blog.didispace.com

9. swagger.contact.email=[e-mail]

10. swagger.base-package=com.didispace

11. swagger.base-path=/**

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

配置说明

默认配置

1. - swagger.title=标题

2. - swagger.description=描述

3. - swagger.version=版本

4. - swagger.license=许可证

5. - swagger.licenseUrl=许可证URL

6. - swagger.termsOfServiceUrl=服务条款URL

7. - swagger.contact.name=维护人

8. - swagger.contact.url=维护人URL

9. - swagger.contact.email=维护人email

10. - swagger.base-package=swagger扫描的基础包，默认：全扫描

11. - swagger.base-path=需要处理的基础URL规则，默认：/**

12. - swagger.exclude-path=需要排除的URL规则，默认：空

13. - swagger.host=文档的host信息，默认：空

host属性从1.3.0.RELEASE开始支持

Path规则说明

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

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

比如，通常我们可以这样设置：

1. management.context-path=/ops

2. swagger.base-path=/**

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

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

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

分组配置

当我们一个项目的API非常多的时候，我们希望对API文档实现分组。从1.2.0.RELEASE开始，将支持分组配置功能。

具体配置内容如下：

1. - swagger.docket.<name>.title=标题

2. - swagger.docket.<name>.description=描述

3. - swagger.docket.<name>.version=版本

4. - swagger.docket.<name>.license=许可证

5. - swagger.docket.<name>.licenseUrl=许可证URL

6. - swagger.docket.<name>.termsOfServiceUrl=服务条款URL

7. - swagger.docket.<name>.contact.name=维护人

8. - swagger.docket.<name>.contact.url=维护人URL

9. - swagger.docket.<name>.contact.email=维护人email

10. - swagger.docket.<name>.base-package=swagger扫描的基础包，默认：全扫描

11. - swagger.docket.<name>.base-path=需要处理的基础URL规则，默认：/**

12. - swagger.docket.<name>.exclude-path=需要排除的URL规则，默认：空

说明： <name>为swagger文档的分组名称，同一个项目中可以配置多个分组，用来划分不同的API文档。

分组配置示例

1. swagger.docket.aaa.title=group-a

2. swagger.docket.aaa.description=Starter for swagger 2.x

3. swagger.docket.aaa.version=1.3.0.RELEASE

4. swagger.docket.aaa.termsOfServiceUrl=https://gitee.com/didispace/spring-boot-starter-swagger

5. swagger.docket.aaa.contact.name=zhaiyongchao

6. swagger.docket.aaa.contact.url=http://spring4all.com/

7. swagger.docket.aaa.contact.email=[e-mail]

8. swagger.docket.aaa.excludePath=/ops/**

9. swagger.docket.bbb.title=group-bbb

10. swagger.docket.bbb.basePackage=com.yonghui

说明：默认配置与分组配置可以一起使用。在分组配置中没有配置的内容将使用默认配置替代，所以默认配置可以作为分组配置公共部分属性的配置。

JSR-303校验注解支持

支持对JSR-303校验注解的展示，如下图所示：

目前共支持以下几个注解：

• @NotNull

• @Max、@Min

• @Size

• @Pattern

贡献者

• 程序猿DD-翟永超

• 小火

相关阅读

长按指纹

一键关注