成熟的 Web API 框架总有一款 API 文档与之伴随，当前最知名的莫过于支持 Open API 的 Swagger 了。Python 的 Flask 框架支持 Swagger UI 也有几条路子
单纯用 Flask 构建 API 的话，细数起来也就 Flasgger 比较合适，如果甩开 Flask 而用 FastAPI 的话，就不用操心 Swagger 了，因为 FastAPI 原生的支持 Swagger。
本文中我们将体验如何使用 Flasgger, 关于使用方法，在它源码的 README.md 已经描述的很清楚了。Flasgger 提供了以下几种主要的使用方式 阅读全文 >>
在命名本文的标题都敲打了几分钟时间，问题很简单，然而用简短的一个标题完全描述出来却有点费事。在 Spring MVC 项目结合 Springfox 来生成 Swagger API 文档时，如果一个资源操作因为请求参数的不同而映射到多个 controller 方法，那么 Swagger 可能只能生成某一个 API 条目，其余都被忽略。至于为什么说是 "可能", 可能正好未遵循命名规范而躲过了这一劫。由此引出
我们这里用了资源操作一词，它包含了两部分信息: 资源与操作，比如 /users/{userId} 是资源，而发生在其上的 HTTP 各种方法，如 POST, GET, PUT, DELETE 等就是操作。而 Spring MVC 中允许我们针对不同的查询参数把相同的资源操作映射到不同的 controller 方法上，也是为了保持逻辑上更为清晰。
比如下面的例子路由配置的例子
GET /users/{userId} UserController.getUserInfo //默认
GET /users/{userId} UserController.getUserInfo //当有 ?source=file 时
GET /users/{userId} CloudUserController.getUserInfoFromCloud //当有 ?source=cloud 时
看到上面资源与操作完全相同，仅仅因为 source 查询参数的不同而映射到三个 controller 方法。用代码体现如下图 阅读全文 >>
前面写过一篇如何建立 一个最基础的 Spring 4 MVC Maven 项目，现在是要在此基础上使用 SpringFox 来生成 Swagger 文档以及 SwaggerUI。Swagger 2 是基于 OpenAPI3.0 的实现，SpringFox 是用于在 Spring 项目中生成 Swagger 文档及 UI, 主要包括两个组件 springfox-swagger2 和 springfox-swagger-ui。
本文是基于普通的 Spring MVC 项目的实例，而非针对 SpringBoot 项目，实际运用应该大同小异，无外乎 SpringBoot 中有许多自动配置项。并且本文也不涉及到 Swagger 众多注解的具体用法，具体请查看源代码或相关文档。
开始本文的示例，首先需要搭建起 Spring MVC 项目，具体做法请参考 一个最基础的 Spring 4 MVC Maven 项目。
对应于两个组件 springfox-swagger2 和 springfox-swaager-ui 的应用，从大尺度上讲有两方面的内容，分别是
使用第一个组件 springfox-swagger2 能够让项目运行期自动生成 Swagger 2 的 JSON API 文档，分两步走
在项目的 pom.xml 文件中加入依赖配置
|
1 2 3 4 5 |
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.8.0</version> </dependency> |
截止目前，springfox 官方已释放出 springfox-swagger2:2.9.0, 但是在 Maven 的中央仓库中只有 2.8.0 版，所就采用 2.8.0 版本 阅读全文 >>