当然，在API的开发过程中，文档编写方面的困难不止一次出现：要么不存在，要么不显示代码中描述的行为。
从开发人员的角度来看，编写文档（仅内部）所花费的时间不会少于编写代码本身的时间。 熟悉吗？ 然后欢迎猫。
有问题吗？
我们的团队已经开发了很长时间的API，这是我们产品的基础，但是那时没有实时用户，因此没有人看到需要记录某些东西以供外部使用的信息。 像所有团队一样，我们从内部文档开始-首先是一种方法，然后是另一种方法。 在我们Confluence的空间中，您可以找到其他十二个页面，这些页面显示了漂亮的样板信息-哪种API方法，它具有什么查询路径，什么参数以及我们在输出中得到什么。
一切都会好起来的，但是代码在不断变化和增长，业务需求也在变化。 随着代码的更改，API可能会更改，这不可避免地导致这些页面上的更改。 好吧，如果只有一页且只有1次。 如果还有更多变化？
我们在参与开发人员的日常活动的同时，尽可能地提出了一个解决方案（我们自己的自行车），而不是考虑编写和更新内部文档。
一些解决方案
对于如何将代码及其规范进行互连，有不同的选择，但是我自己区分两个：
我将从第二个开始，从最不适合我们的选项开始。
首先，规范，然后是代码，它是关于基于规范的代码生成的，也就是说，直到编写规范，该代码才存在。
最简单的示例是Swagger Codegen。
我们公司的团队在他们的产品中使用了这种方法，但是对于我们来说，这不是很合适。 在遇到需求时，我们已经编写了许多API方法，因此为了文档起见，我们不想从根本上改变开发流程-首先我们编写草案，然后编写代码，然后再编写规范描述。
首先是代码，然后是规范-一切都很简单，首先我们编写代码，然后编写规范。 但是随后出现了一个问题-是否我们不想做不必要的动作以便生成规范？
我们公司中的许多应用程序都使用这种方法，但是它并不是特别自动化-API方法使用各种注释进行加权，并在此基础上生成规范。 但是这些相同的注释通常与现实不符，因为应用程序的需求和功能正在不断增长和变化。
我对自己说：
“你是一名程序员。”并决定编写一个小的原型，使我不必编写所有这些常规垃圾。
在完成下一个任务并编写第n个功能测试时，我意识到我们已经掌握了该规范的所有信息。
我们的功能测试包含几乎所有我们需要的信息：
- 所谓的
- 所谓的（参数，正文，标题等）
- 预期会得到什么结果（状态码，响应正文）
为什么不做自己的自行车？
我们通常在规范中编写的几乎所有内容。 小写的情况-编写这种情况的代码。
由于我们的应用程序是用php编写的，因此反射对我有所帮助。 使用一点反射的魔术，我们收集了所有可用的API方法，从功能测试中获取数据，提取有关授权及其类型的数据。 从通常的注释到方法，我们获得了方法本身的描述。 将所有这些混合在一起，并为解决方案中使用的框架提供特定功能，然后在几周内我们得到了一个几乎不需要开发人员花费时间的解决方案。
生成规范只是第一步-您需要从规范中获取可由外部开发人员提供的文档。 文档的要求之一是应以多种语言显示，但是目前，我们仅以英语生成文档。 到目前为止，足够了，但是有必要将一种用于接收传输的机制连接到我们的规范生成方案。
最初我们解决的问题。 但是使用此解决方案存在许多风险：
- 价格支持您自己的自行车
- 扩展必要的功能
- 更新和同步翻译
必须牢记这些风险，如果这些风险开始起作用，请采取措施。