1. 介绍
Springfox Java库套件主要是为了能够让使用Spring系列项目编写的JSON APIs自动生成机器和人类可读的规范。Springfox的工作原理是在运行时检查一次应用程序，根据Spring配置、类结构和各种编译时java注解推断API语义。
1.1. 历史
Springfox是从马蒂·皮特最初创建的一个项目演变而来的，并被命名为swagger-springmvc。很多荣誉都归功于马蒂。
1.2. 目标
- 支持更多针对JSON API规范和文档的不断发展的标准，例如：swagger、Raml和jsonapi。
- 提供更多Spring webmvc外的Spring技术的支持
- 从哲学上讲，我们不鼓励在运行时使用对服务描述不重要的(swagger-core)注解。例如，Jackson注解应该总是胜过
@ApiModelProperty，或者具有比@ApiModelProperty更大的权重，又像是，@NotNull或指定@RequestParam#Required应该始终取胜。在无法推断服务/模式特征的情况下，注解仅用于补充文档或覆盖/调整生成的规范。
1.3. 它不是什么
它不是由Spring框架贡献者认可或批准的
1.4. 开发环境
-
文件(File) >> 打开(Open) >> build.gradle
-
确保选中“使用默认Gradle包装器”选项。
-
首次构建
./gradlew cleanIdea idea-
要发布到本地maven存储库，请执行以下操作
./gradlew clean build publishToMavenLocal -i
此版本针对将软件发布为binray/Sonatype进行了优化。为了让Gradle确定版本，Gradle插件依赖于本地文件夹作为克隆的git存储库。下载源代码存档和构建将不起作用！
1.4.1. 预提交构建
-
代码质量(代码覆盖率、检查样式)
./gradlew check
1.4.2. 创建参考文档
构建所有当前文档(构建手写文档和javadoc)，请执行以下操作：
./gradlew allDocs
档在build/all-docs文件夹中生成。发布当前文档的步骤(快照)
./gradlew publishDocs
1.4.3. 更新契约测试
在开发新契约测试时，为了便于用新契约更新现有测试，请取消对swagger-tract-test/build.gradle中以下行的注解。通常，当我们为已经修复的bug或添加的功能添加新的约定测试时，会发生这种情况，我们在BugsController或FeatureDemonstrationService中创建一个端点来演示新的修复或行为。
// NOTE: Uncomment to bulk update contracts
//test {
// systemProperty("contract.tests.root", "$projectDir/src/test/resources")
// systemProperty("contract.tests.update", true)
//}
1.4.4. 持续集成环境
1.5. 发布
要发布Springfox的非快照版本，请执行以下操作：
- 执行Release命令：运行Release需要以下环境变量：
GITHUB_TOKENBINTRAY_USER_NAMEBINTRAY_PASSWORDSONATYPE_USER_NAMESONATYPE_PASSWORD
建议将autoenv与Repo根目录下的.env文件一起使用。
./gradlew release -PreleaseType=<MAJOR|MINOR|PATCH> -i
./gradlew publishDocs
发布步骤如下：
- 检查git工作区是否干净
- 检查本地git分支是否为主
- 检查本地git分支是否与Origin相同
- Gradle测试
- Gradle检查
- 将所有工件上传(发布)到Bintra
- 在
version.properties中升级项目版本 - Git tag发布
- Git推送
1.5.1. 快照
通常由CI服务器完成
./gradlew publishSnapshot
1.5.2. 覆盖部署
需要绕过标准发布流并直接上传到binray，请使用以下任务 - 在version.properties中手动设置版本
./gradlew clean build bintrayUpload -PreleaseType=<MAJOR|MINOR|PATCH>
--stacktrace
1.5.3. 发布文档
需要更新现有版本的文档，请传递updateMode开关
./gradlew releaseDocs
1.5.4. 贡献
获取指导原则请参阅维基
1.6 支持
如果发现问题或错误，请通过Springfox Github项目提交
2.快速入门
2.1. 依赖
Springfox库托管在bintray和JCenter上。以下是访问链接：
- Release：
- Snapshot
Springfox有多个模块，依赖关系将根据所需的API规范标准而有所不同。下面概述了如何引入springfox-swagger2模块，该模块用于生成Swagger2.0API文档。
2.1.1. Gradle
Release
repositories {
jcenter()
}
dependencies {
compile "io.springfox:springfox-swagger2:2.9.2"
}
Snapshot
repositories {
maven { url 'http://oss.jfrog.org/artifactory/oss-snapshot-local/' }
}
dependencies {
compile "io.springfox:springfox-swagger2:2.9.2-SNAPSHOT"
}
2.1.2. Maven
Release
<repositories>
<repository>
<id>jcenter-snapshots</id>
<name>jcenter</name>
<url>https://jcenter.bintray.com/</url>
</repository>
</repositories>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
Snapshot
<repositories>
<repository>
<id>jcenter-snapshots</id>
<name>jcenter</name>
<url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
</repository>
</repositories>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2-SNAPSHOT</version>
</dependency>
网友评论