Springfox参考文档(Springfox Reference Documentation 中文)

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. 持续集成环境

Circle CI

1.5. 发布

要发布Springfox的非快照版本，请执行以下操作：

• 执行Release命令：运行Release需要以下环境变量：
• GITHUB_TOKEN
• BINTRAY_USER_NAME
• BINTRAY_PASSWORD
• SONATYPE_USER_NAME
• SONATYPE_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：
  • https://jcenter.bintray.com/io/springfox/
  • http://jcenter.bintray.com/io/springfox/
• Snapshot
  • http://oss.jfrog.org/simple/oss-snapshot-local/io/springfox/
  • http://oss.jfrog.org/oss-snapshot-local/io/springfox/

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>

3. 快速入门指南

查看剩余全部