如何真正实现由文档驱动的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接口管了解决方案的领军者，支持自动读取代码注解生成API文档，极大地提高了开发者文档撰写的效率，欢迎有兴趣的登陆EOLINKER?API Studio，体验研发能力释放的高效！https://www.eolinker.com

总结

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

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

原文作者：Guy Levin

翻译和修改：EOLINKER

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