先写接口文档还是写代码(接口文档是前端写还是开发写)

什么是接口文档，如何写接口，有什么规范

首先要有一个文档的标题，XXX接口文档，符合当前文档的说明，文档的生产日期，以及公司名称等。现在开始写一个dubbo接口文档，定义标题，以及日期，这里公司省略。使用confluence在线编辑，Confluence为团队提供一个协作环境。团队成员协同地编写文档和管理项目。从此打破不同团队、不同部门以及个人之间信息孤岛的僵局，Confluence实现了资源的共享。

接下来要有当前文档的版本修订信息，即为历史修订信息，应当包含基础的信息有：版本号、修订日期、修订人、修订说明等。

开始编写文档的目录结构，注意大标题和小标题的使用，需要合理的运用说明。首先当然是文档的说明信息，再来是一些准备信息和流程信息，然后开始接口说明，最后可以有举例、常见问题、注意事项、响应码的说明信息等等。

下面开始按照文档的目录结构逐一进行详细的介绍说明，比如文档说明的介绍，用高效简洁的语言明确的说明文档信息，注意文档中大标题应当字体大小样式一致，小标题也应当字体大小注意保持一致。

简单的说明技术资料获取及准备，确认调用系统信息比较重要，需要确认编码格式，防止乱码，确认当前的文档版本是否是要使用的版本，否则白做无用功，项目的搭建环境简单说明即可。

开始说明接口的调用流程，如何调用接口，需要做的一些准备，说明引入相应的依赖以及配置需要配置的文件。

现在可以开始接口的说明，接口的说明信息应当包含接口的名称，接口的地址，接口的协议，然后针对当前接口下的方法说明。

方法的说明应当包含方法的描述，即其作用，方法的请求参数说明，以及响应的参数说明，参数说明应当包含参数的类型，参数名称，参数的含义，并且备注参数是否必须传递。

9

接口说明完之后，就是文档的末尾，有注意事项添加一些注意事项，或者附录说明，添加标注。

接口有什么用，还是要自己写代码啊

接口的一个基本用途，规定子类的行为。更为广阔的用途是接口为其他人使用者提供用途，模块和模块之间的解耦。

接口开发是需要编写代码,接口的使用也需要根据使用编写代码来使用接口。以后程序的扩展性提供基础。“对修改封闭，对扩展开发”。

使用接口的话，在使用它之前，就要想好它要实现的全部功能（接口实际上就是将功能的封装）。确定下这个接口后，如果用户需求变了，只要重新写它的实现类，而其他人只会调用这个接口，只需要接口提供的功能。这样，很可能只需要把修改代码就可以了，其他什么都不用做。同时：这样做的话，使得开发人员能够分工明确，只要确定下来接口了，就可以同时进行开发，提高开发效率。另外，使用接口还有使用方便，可读性强，结构清晰等优点。

人类与电脑等信息机器或人类与程序之间的接口称为用户界面。电脑等信息机器硬件组件间的接口叫硬件接口。电脑等信息机器软件组件间的接口叫软件接口。

硬件接口，主机的对外接口，通过接口接入其他硬件设备。

软件接口，软件的未来其实在很大程度上要指望软件接口的前景如何。我们知道，计算机世界里的接口这两个字具有两种众所周知的含义：其一是指软件本身的狭义“接口”，比如各种软件开发API等。其二则指的是人与软件之间的交互界面。

应用程序编程接口，简称API（Application Programming Interface），就是软件系统不同组成部分衔接的约定。

把这种人-软件之间的接口称作“用户界面”,也就是“UI”。这里要讨论的前一种定义： 软件不同部分之间的交互接口。通常就是所谓的API――应用程序编程接口，其表现的形式是源代码。API的发明和发展大大促进了计算机产业的进步，同时API几乎决定着日常运算的各个方面。

大多数程序员秉承为软件用户设计优秀的用户界面思想，这一点早已深入人心。可是，另一方面，如何实现合理的软件API却只为少数人所重视。历史证明，所有在应用上获得成功的软件或者Web应用无一不是首先在API的设计上满足了用户的需求，即便这些用户几乎从不直接使用这些API！

程序接口是操作系统为用户提供的两类接口之一，编程人员在程序中通过程序接口来请求操作系统提供服务。

如何优雅的“编写”api接口文档

一些刚开始写接口文档的服务端同学，很容易按着代码的思路去编写接口文档，这让客户端同学或者是服务对接方技术人员经常吐槽，看不懂接口文档。这篇文章提供一个常规接口文档的编写方法，给大家参考。

推荐使用的是docway?写接口文档，方便保存和共享，支持导出PDF MARKDOWN，支持团队项目管理。

一、请求参数

1. 请求方法

GET

用于获取数据

POST

用于更新数据，可与PUT互换，语义上PUT支持幂等

PUT

用于新增数据，可与POST互换，语义上PUT支持幂等

DELETE

用于删除数据

其他

其他的请求方法在一般的接口中很少使用。如：PATCH HEAD OPTIONS

2. URL

url表示了接口的请求路径。路径中可以包含参数，称为地址参数，如**/user/{id}**，其中id作为一个参数。

3. HTTP Header

HTTP Header用于此次请求的基础信息，在接口文档中以K-V方式展示，其中Content-Type则是一个非常必要的header，它描述的请求体的数据类型。

常用的content-type：

application/x-www-form-urlencoded

请求参数使用“”符号连接。

application/json

内容为json格式

application/xml

内容为xml格式

multipart/form-data

内容为多个数据组成，有分隔符隔开

4. HTTP Body

描述http body，依赖于body中具体的数据类型。如果body中的数据是对象类型。则需要描述对象中字段的名称、类型、长度、不能为空、默认值、说明。以表格的方式来表达最好。

示例：

二、响应参数

1. 响应 HTTP Body

响应body同请求body一样，需要描述请清除数据的类型。

另外，如果服务会根据不同的http status code 返回不同的数据结构， 也需要针对不同的http status code对内容进行描述。

三、接口说明

说明接口的应用场景，特别的注意点，比如，接口是否幂等、处理是同步方式还是异步方式等。

四、示例

上个示例（重点都用红笔圈出来，记牢了）：

五、接口工具

推荐使用的是（以前叫小幺鸡） 写接口文档，方便保存和共享，支持导出PDF MARKDOWN，支持团队项目管理。

编程的文档是在写代码之前还是在写代码之后？？

可以说是在编程过程中所写的。比如一个程序的如干函数，每写完一个函数可以写一个与之相关的文档进行说明，用来让用户能够更好的了解程序的应用和编程合作人员的理解

软件开发可以先写程序再写文档吗

那要看是什么文档了，

1) 一般来说分析、设计文档应该是要先有的，特别是开发比较复杂的系统，如果没有很好的规划设计，程序结构可能会比较混乱。

所以应该先有文档，当然这个文档可以不是十分的全面，可以在开发过程中逐步补充完善，但至少是要有框架式的文档。

2) 对于小型程序开发，一个人就搞定了；你可以先写好程序，然后再把关键功能、算法、流程什么的整理成文档，以免自己以后忘掉了难以维护。

3) 用户帮助文档之类的肯定是要等程序完成、测试OK再写了。

文档最主要的作用，我认为一是帮助你理顺设计、开发思路，有句话Once a problem is described in sufficient detail,its solution is obvious;二是方便后续维护。