如何真正实现由文档驱动的API设计？

前言

本文主要介绍了一种新的开发思路：通过反转开发顺序，直接从API文档中阅读代码。作者认为通过这种开发方式，你可以更清楚地知道文档表达出什么以及它应该如何实现。

如果单从API文档出发，由于信息量不足，通常很难了解它具体想实现的功能，正因为有这种假设的存在，使得经常在开发之后才会想起对文档进行完善。但这种习惯对于任何开发人员而言，都不是一个好事情，在一个项目中他们会被分配完成不同的任务，不管是什么任务，必须要准确理解每个功能后，才能找到合适的方法完成工作，而一份完善的文档的作用就是能让你更好的理解具体的任务。

我们面对项目验收不断临近的截止日期，更不得不将精力全都放在开发上，导致几乎没有时间处理和完善项目文档，一般只会写个大概。因此，当你发现了文档上十分简略的信息时，那只能寄希望于回忆起当时的开发细节，不然验收时根本无从说起。

如果在验收的标准中，对文档的完整度和正确性提出要求，并且用户能对此进行评级，那文档的完善程度将会大大提升。

在编写大量代码之前，如果已经在文档中记录了所需的详细信息，那么这个文档将成为开发团队的宝贵资源。因为这个文档可以在开发团队和测试人员之间共享，所有人都可以同时使用这样的API。反过来说，通过团队的交互性凸显了文档在API开发中的重要位置。

当你想找到某一个文档时，通过交互协作的方式，你能够直接从项目中调用这个文档，这将有助于开发人员在完成任务时更方便地调用API，有效减少开发人员调试接口的时间。

我们知道了API文档的重要性，下面我们讲一下文档设计应该如何设计。

3个API文档设计中重要功能

这些是我认为在文档中应该存在的三个功能：

1.时刻保持同步性，这意味着如果开发过程中增加了什么内容，那么从文档中也应该马上得知，即便是进度滞后，也应该保证文档内容在即将发布时与开发进度是一致的。

2.文档内容应该提供项目整个功能的完整内容，同时实现的方法也应该记录在文档中，供开发人员回看，方便查漏补缺。

3.文档应该作为指导和规范，帮助不同分工的开发人员完成目标统一的业务，也可用于测试API，并有助于增强开发团队沟通。如果有条件的话，还可以对完善文档的人提供奖励。

基本的API文档部分

如何验证API使用者的身份呢？首先你需要一个身份信息验证方案。

1.如果你使用的是OAuth，请不要忘记在文档中解释如何设置OAuth并获取API密钥。

2.你需要记录开发中遇到的错误以及它们导致的问题，你应该在文档中解释这个错误是否违反了错误标准，即失败示例。

3.你需要记录包含端点和有关如何使用它们的信息，包括请求信息和返回信息。这是API文档的最主要部分。

记录好这三个部分，你将有一个良好的开端，因为你已经有了使用API所需的大部分内容。同时对于测试人员来说，根据你的文档进行API测试会方便很多。

但这往往还是不够的，当你遇到更复杂的情况，你还得提供额外的API的非功能性方面的文档来补充说明。

API文档还应包含哪些内容

1.解释API文档中每个参数作用。

2.各种语言和工具（cURL，Postman等）的API调用示例。这些示例可能会被多次使用，可以说是API文档中最重要的部分。

3.详细说明调用API时的工作流程。

4.API提供程序采用的设计原则概述，例如REST（特别是超媒体），HTTP代码等。

5.有关身份验证的信息，包括可能实现的其他方案，如OAuth或OpenID Connect。

6.有关错误处理的一般信息以及有关HTTP返回码的信息。

7.一种交互式API资源管理器，允许开发人员轻松地将所有这些信息变为现实。

开始撰写你的API文档

首先要将每个功能的需求转换为文档，同时你的文档应该是可分享的。只有这样，查看的人可以通过文档获得有关如何正确开发项目的信息，尤其是需要理解文档以解释项目的内部开发人员。

在编写API项目的文档之后，如果有条件的话，最好将文档的书面注释和其他内容转换为丰富多彩的网站和其他可自定义的模板，将有助于为项目生成完整的站点。

3 个API文档模板标准

在所有API文档格式中，其中有三种值得一提，因为它们允许你以手动或者自动的方式设计API：

1.Swagger和Open API。你可以轻松生成自己的API服务器代码，客户端代码和文档本身。Open API Initiative（OAI）专注于基于Swagger规范创建，发展和推广供应商中立的API描述格式。

2.RAML。RESTful API建模语言系统提供了一种能指定API使用模式的简便方法。

3.API Blueprint。这是一种基于Markdown格式的标准，可让你轻松地从文档中生成代码。

除了作者提到的三种API标准外，EOLINKER也支持自动读取代码注解生成API文档，极大地提高了开发者文档撰写的效率，有兴趣的试试 EOLINKER API Studio，我这里就不多说了，方正效率的确提升了很多！https://www.eolinker.com

总结

作为开发者，如果你想保证他人能够很好地理解你的API，那么在开发中就必须清楚文档的重要性。虽然有些人也承认上述的观点，认为使用API文档启动项目是一个好主意，但实际上大多数人都还在努力编写与文档无关的内容。

如果一开始就规划好你的文档，一旦确定后，那么会有更多的时间来处理主项目的内容。从长远来看，拥有优秀的文档可以为你节省大量时间，并可以帮助你更轻松地构建项目。

原文作者：Guy Levin

翻译和修改：隔壁王书

原文地址：https://dzone.com/articles/documentation-driven-api-design