如何逐步审核API

API是一个重要的软件中介，可以实现两个应用程序之间的通信。它提供了软件灵活性，简化了设计过程，并简化了管理。当谈到软件生态系统时，一切都需要符合最高标准，因为一个精心规划的生态系统为使用服务提供了很高的舒适度。推荐改进的最有效方法是强大的专业知识。继续阅读，了解我们是如何一步一步地进行API和文档审核的

API和文件审核

起初，我们决定以黑盒测试的方式进行审计。这意味着我们无法访问代码或内部文档。我们主要根据网站上提供的材料进行审计。在这个阶段，我们无法估计我们的审计相对于所有API方法的覆盖率。后来，通过获得源代码访问权限，我们能够有效地准备所有控制器、APIs和方法的规范，以及审计计划。我们将错误和问题分为以下几类：

遗漏信息
文档结构不良
API可用性
设计不符合标准
错误和拼写错误
后端错误

审计小组发现了下表所列的大约21个问题。

Image 1: Category - number of bugs: Missing information - 8; Bad documentation structure - 4; API usability - 5; Design against standards - 2; Mistakes and misspellings - 1; Backend errors - 1; Total - 21.

我们在进行审计时注意的最后一个因素是使用API的开发人员的总体印象。

第1步：API源代码分析、内部文档和API审计计划执行

API审核计划包含以下内容：

编写API业务和系统分析文档及相关产品（文档、示例、API注释）。
用所谓的高级API描述语言编写语义API描述。请注意，除了API规范之外，此任务还将包括静态文档项的编辑和转换。
选择可用的工具（或创建专用脚本）及其配置，以实现与API规范（见上文）和CI/CD的连接，从而自动化代码/规范合规性验证、生成交互式文档和自动化测试。当代码发生变化时，文档也会发生变化，并进行自动测试，以证明文档和API的符合性。

以下是对CI/CD流程的修改，其中包含了自动化验证、测试和创建交互式文档的新元素。这些行动不仅改善和加强了流程，自动化还会影响新功能的实施速度。

第2步：API改进

第三步：开发者中心

如何简化API测试

我们选择了5种测试方法，并使用元语言对其进行了描述。根据所选择的概念，我们将能够在CI/CD过程中包括文档和API合规性验证、自动测试或交互式文档。为此，我们使用了：

API蓝图（用于web API的高级API描述语言），
Apary（作为API蓝图在线编辑器，用于创建交互式文档），
Dredd for testing（一种语言识别命令行工具，用于根据API的后端实现验证API描述文档）。

Image 4: Screenshot that shows technical documentation about API services.

1.API蓝图

2.互动文件（Apiary）

下面的屏幕截图显示了文档的主视图。

Image 5: The screenshot presents the main view of the documentation.

简介（包含快速入门），
参考文献（API），
数据结构（对象描述）。

简介部分包含有关如何设置一切以便能够使用API的信息，例如，如何对系统进行身份验证或注册。参考部分包含API中所有可用资源的实际定义。每个对象都有自己的部分，其中包括一组指向每个方法定义的链接。数据结构部分包含作为API一部分的所有对象及其定义的列表，如参数和类型。

Image 6: The screenshot presents the Introduction section that contains the information how to set up everything to be able to use the API.

下面的屏幕截图显示了主文档视图，其中包含打开的调用方法详细信息和尝试控制台面板。它显示了URL、带描述的URI参数、请求和标头的标头、示例正文和响应方案。

Image 7: The screenshot presents the main documentation view with an opened call method details and Try console panel. It shows the URL, URI parameters with description, headers for request and headers, example body, and scheme for response.

下面的屏幕截图显示了调用方法的详细信息，可以生成许多流行编程语言的代码示例（供您的应用程序使用）。这有助于促进通过API接口将任何应用程序或系统与API平台集成的过程。可用的语言有cURL、Java、JavaScript、Node.js、Perl、Python、PHP、Ruby、Go、C#、Visual Basic、Groovy、Objective-C、Swift。

Image 8: The screenshot presents a call method details with a possibility to generate code examples (for the use in your application) in many popular programming languages.

下面的屏幕截图显示了尝试控制台面板，该面板提供了直接从文档中测试API的机会。它允许我们放入自定义参数、标头和正文，并向服务器创建完全自定义的请求。我们还可以通过模拟端点调用方法，这使我们能够检查API周围的所有流量。

Image 9: The screenshot presents the Try console panel which offers an opportunity to test API directly from the documentation.

3.自动化API测试（Dredd）

Image 10: Dredd reads API description and step by step validates whether API implementation replies with responses as they are described in the documentation.