基于swagger进行接口文档的编写

0. 前言

近期忙于和各个银行的代收接口联调，根据遇到的问题，对之前编写的接口进行了修改，需求收集和设计接口时想到了方方面面，生产环境下还是会遇到意想不到的问题，好在基本的执行逻辑已确定，因此只是对接口进行了一些微调，但是收钱无小事，之前在代码编写时对参数进行了很多的校验，代码修改之后一个参数的对不上都会导致接口调用的失败，所以接口文档也要进行修改。正好趁此机会利用swagger对接口文档进行了重构，记录一下搭建过程，也借此谈一下对接口设计及文档编写的一点心得。

1. 项目中添加swagger插件

引入jar包

        <dependency>
            <groupId>com.fasterxml</groupId>
            <artifactId>classmate</artifactId>
            <version>1.4.0</version>
        </dependency>

        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.8.9</version>
        </dependency>

        <!-- swagger2核心依赖 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>

        <!-- swagger-ui为项目提供api展示及测试的界面 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>

        <!-- spring相关jar包 -->
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-core</artifactId>
            <version>4.2.6.RELEASE</version>
        </dependency>
   
<!-- other jars-->

后续配置Maven + SpringMVC项目集成Swagger中有介绍，这里略过。

2. 生成接口

配置swagger只发现配置@Api注解的接口类

只对代收的类进行@Api注解标注，发现里面的所有接口，仅为调试，其他的方法级别的注解懒得加了

访问 http://localhost:8080/portal/swagger-ui.html#/

可以对每个接口进行传参调用。

3. 接口文档编写的几项原则

写接口文档时首先得知道你的读者是接口调用方的开发人员，是除你之外需要对这个接口最熟悉的人。所以写文档时需要注意几个原则：

• 格式简洁：文档需要有简洁的书写格式，体现在文档目录的设计、文档目的、接口介绍语言的精炼。
• 逻辑清晰：文档内容的介绍需要具有清晰的逻辑，具体到每个接口的介绍、调用及返回，得有清晰的路线。
• 内容全面：接口设计的目的、请求及参数格式、响应及响应格式，最好的检验方法是使用者拿到该文档之后能够自行成功的完成接口的调用。
• 有据可查：使用者在调用某接口时如果出错，是否能够凭借返回信息认识到出错的原因进而调整，而不必调用失败时一头雾水，这需要在设计者接口设计时就设定好各种错误的返回标识。

4. 接口文档内容编写

4.1 功能介绍

4.1.1 前言

主要介绍方案设计的目的、此方案所有接口共同实现的笼统的功能介绍、接口设计方和接口调用方（一般都是乙方。。。）各方的职责，等等

4.1.2 功能说明

详细介绍各个接口所实现的功能，使读者对各接口的作用有一个了解。内容尽量保持简洁全面，没必要把底层实现也写进去。

4.2 系统接口约定

这是整个文档最重要的部分，使用者可能不会看前言和介绍，但他要实现接口调用，必须参考约定中的请求格式及各项约定。

4.2.1 系统约定

介绍调用者和提供者共同遵守的编码约定、通信方式（RESTful 风格接口）、数据格式（JSON 或 XML）、编码方式（UTF-8）等。

4.2.2 接口数据格式

各个接口的请求介绍（请求参数的含义、请求地址、方法名称、请求格式），响应介绍（响应参数介绍、响应格式）

涉及到其他文件调用的也要详细介绍文件编写所要遵循的格式，最好能够内嵌附件。（如系统对账，需要读取ftp服务器上的csv文件内容与系统中比对，文档中就需要添加csv文件的编写规范，如：文件命名格式、文件内容格式、大小限制等）

4.3 返回值对照

接口调用成功的话返回约定好的返回值，更需要注意的是接口设计时就需要考虑到捕获各种错误（可通过枚举在系统中提前定义好各种错误的返回值），调用失败的话返回准确的提示信息，省的调用方一调用出错就来找你，对双方的时间都是一种浪费。

5. 接口文档示例

5.1 目录展示

5.2 接口请求部分内容

5.2.1 请求格式

介绍各个请求参数的定义和所要遵循的格式

5.2.2 请求地址、方法及格式

5.3 接口响应部分内容

5.3.1 响应格式

介绍各个响应参数的定义和所要遵循的格式

5.3.2 响应参数格式实例

5.4 返回码对照

定义返回码的值，调用成功或失败可参照返回码