如何真正实现由文档驱动的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