基于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. 接口文档编写的几项原则

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

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