Swagger 2（Open API v3.0） Java 文档生成指南（上）

接口文档生成器指的是写好了 API 接口 之后，让前台开放人员（包括不限于 H5 前端、iOS/Android 客户端、小程序等）调用接口时的文档。个人比较主张“代码即文档”，即文档编写在源码之中。

先全网选型了一下，发现适合 Java 的有下面几种开源的方案。

• Swagger ，也就是本文的主角，实际情形比较复杂，下面再说
• apidoc.js ，node.js 方案，通过注释写文档，而不是真正代码，舍弃之
• RAP ，淘宝出品，没深入了解
• Api2Doc2 ，国人出品，for Java 的，励志做 Java 届最好用的文档工具，不过听过生成的文档还要 SpringBoot 来跑，太重了，舍弃之。

看来也只是 Swagger 比较合适。然而 Swagger 这货也不简单。首先是搞 Java 言必称 Spring，所以文档 工具 也首推 for Spring 的（很文章介绍 Swagger 的一个插件，实际 Swagger 真身是 Swagger Core）。我不是搞 Spring 的就不能用 Swagger 呢？肯定不是， Swagger 不是 Spring 专属的，只不过 Spring 一家独大，所以网上资料也净是它的，连墙外的 google 也是……

刨英文吧，官方的文档是唯一的指南了……

第二个问题，Swagger 本身的问题，这货通过注解实现文档，旧版的是自己的注解，但后来呢，成立的一个什么 Open API 组织还是什么标准，针对文档服务提出新的开放规范。好吧～旧的注解通通要变身了，所以呢，现在很多文章的停留在旧版的注解上。新版的还是要看官方文档。

那咱就用新版吧～

可是怎么用呢？Swagger 这货介绍新版文章几乎为 0，官文又写得云里雾里，我悲苦逼呐～说要 jetty 服务器，然后我的 maven 下载 jar 又文件损坏，搞一大轮，发现 tomcat 7 不行要 tomcat 8，shit 几乎快放弃。

抱着这种想法，通常是柳暗花明又一炮的时候，——我发现它的 simple 项目，都齐备着呢，不同开源项目都有，我想要的是最普通的 Servlet 那个，也有，于是 checkout 下来跑一下，齐活了。

使用说明

首先，Swagger 是这样子的：

• 通过注解编写文档，这很科学，没毛病
• 除了自己的注解，还能辨识来自 javax.ws.rs 即 JAX-RS（Java API for RESTful Web Services） 的注解。如果你的接口项目是用 JAX-RS，那就完美了；如果你不知道这是啥，还是先百度下。反正就是 Java 的一个标准，我们用的是它注解。
• 官文说要 Jetty 但 tomcat 也行，不过因为一个 jar 包版本问题，得 Tomcat 8 才行
• 实际引用的是 Swagger Core，for 普通 Java 项目的。如果你用 Spring Boot 这里跑错片场了。
• Swagger Core 能解析代码的文档部分，形成 YAML、JSON 定义文件，这是给机器看不是人看的。不能直接渲染最终的 HTML/Markdown，要渲染出漂亮的文档， 那是 Swagger UI 干的事情。所以得先导出定义文件再弄文档页面。

其次，是一些相关有用的网址：

• Swagger Core 项目主页 https://github.com/swagger-api/swagger-core
• 官文（洋文） https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X—Getting-started
• 样例项目 https://github.com/swagger-api/swagger-samples/tree/2.0/java/java-jaxrs2-openapiservlet

普通 Servlet 样例

官方样例的“纯度”不是很够，参杂其他多余的依赖，于是我做了一个普通 Java Web 项目来跑，清爽。

1、新建 Web 项目并将其转为 Maven 项目，添加下面依赖。

<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-jaxrs2</artifactId>
    <scope>compile</scope>
    <version>2.0.4</version>
</dependency>
<!-- 做 RESTful 接口的注解  -->
<dependency>
    <groupId>javax.ws.rs</groupId>
    <artifactId>javax.ws.rs-api</artifactId>
    <version>2.1</version>
</dependency>

2、修改 web.xml，增加一个 servlet，访问生成的文档定义文件。

<servlet>
    <!-- 生成接口文档服务 -->
    <servlet-name>OpenApi</servlet-name>
    <servlet-class>io.swagger.v3.jaxrs2.integration.OpenApiServlet</servlet-class>

    <init-param>
        <param-name>openApi.configuration.resourcePackages</param-name>
        <param-value>io.swagger.sample.resource</param-value><!-- 指定扫描的包 -->
    </init-param>

    <!-- 另外可以在 classpath 中引入配置文件  openapi-configuration.json or openapi-configuration.yaml  -->

    <!-- 还可以在下面配置中指明配置文件的位置 -->
    <!-- <init-param> <param-name>openApi.configuration.location</param-name> 
        <param-value>/openapi-configuration.json</param-value> </init-param> -->
    <load-on-startup>2</load-on-startup>
</servlet>

<servlet-mapping>
    <servlet-name>OpenApi</servlet-name>
    <url-pattern>/openapi/*</url-pattern>
</servlet-mapping>

3、写一个测试，在 java 中添加 Swagger 注解，写上你的文档，

注解很多的，看你怎么写文档。

4、运行起来，就是 Run Server，Swagger 会在 Tomcat 启动时解析文档。启动后，访问 Servlet，如 http://localhost:8080/test_doc/openapi/openapi.json ，如无意外会是：

好了，这就得到文档的定义文件。

接着就是生成漂亮的 html，可俺还不会，没研究出来 Swagger-UI～唉.

另外可以在 Swagger Editor http://editor.swagger.io/ 中预览下，就是把定义文件的内容粘贴到 editor 里面去。