小知识，大挑战！本文正在参与“程序员必备小知识”创作活动。
随着前后端分离的普及，日常code中前后端人员扯皮是一个非常常见的事情，所以博主在公司的接口与接口文档编写过程中，制定了一系列的接口文档编写规范。使接口查找更加的明确，入参与出参更加的规范化。这样会大大减少前后端人员沟通的时间。
1.代码规范
- 将同一业务的接口写于1个类中，并写明业务名称，实现方式见图2。
- 详细描述接口，且指定好请求类型，切记不要使用requestmapping，实现方式见图2。
这里有的同学问了，根据restful规则，接口路径只应该是名词，你这不专业啊。因为博主所在公司规模较小，而且人员素质比较一般，所以为了避免在开发时出现一些意外，所以此处并没有采用。
- 写好入参与出参的描述，且入参必须为对象类型。出参也为对象类型。严禁基本类型出入参，实现方式见图2。
- 建立不同的vo返回对象，防止返回值污染。
避免一个vo对象所有的接口都使用，返回了一大堆没有用的字段。
2.swagger导出为word
在编写完swagger后，后续可能需要word来存档或者提供给客户做详细设计。如果重新编写是一个非常二的事情。这里推荐开源项目来处理。他的原理就是访问swagger提供的接口来获取文档数据，然后在渲染成word文件。
1.下载项目
2.修改配置
这里指定的是你需要导出项目的端口。/v2/api-docs为swagger对外提供数据的接口。
3.导出文档
运行项目，请问http://127.0.0.1:8080/swagger-ui.html（开源项目路径）。这里他提供了几个接口，见下图。
这里我们选择：
将 swagger 文档一键下载为 doc 文档，然后点击 try it out，继续点击download即可完成下载。
