Spring MVC 项目中用 SpringFox 生成 Swagger2 API 文档

逃离我推掉我的手 2022-05-25 04:16 203阅读 0赞

前面写过一篇如何建立 [一个最基础的 Spring 4 MVC Maven 项目][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 项目][Spring 4 MVC Maven]。

对应于两个组件 `springfox-swagger2` 和 `springfox-swaager-ui` 的应用，从大尺度上讲有两方面的内容，分别是

## 一：生成 Swagger 2 的 JSON API 文档 ##

使用第一个组件 `springfox-swagger2` 能够让项目运行期自动生成 Swagger 2 的 JSON API 文档，分两步走

### 添加 springfox-swagger2 依赖 ###

在项目的 pom.xml 文件中加入依赖配置

<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 版本  [阅读全文 >>][Link 1]

[Spring 4 MVC Maven]: https://yanbin.blog/basic-spring-4-mvc-maven-project/
[Swagger]: https://swagger.io/
[Link 1]: https://yanbin.blog/springfox-swagger2-generate-api-documet/#more-8665