API已成为现代软件开发的组成部分，使应用程序可以相互通信并交换数据。但是，建造API只是战斗的一半。没有适当的文档，开发人员可能会难以了解如何使用API​​，从而导致时间和资源。这是API文档的来源。

OpenAPI是一种用于描述RESTFUL API的广泛使用的规范。凭借其强大的模式和文档功能，它现在是de facto API文档的标准。在本文中，我们将探讨API文档的重要性，介绍OpenAPI，并提供有关如何使用GO编写OpenAPI文档的示例。

让我们潜水！

什么是API？

API或应用程序编程接口是一组用于构建软件应用程序的协议，例程和工具。 API允许不同的应用程序相互通信，从而更容易共享数据和功能。 API可以采用许多不同的形式，包括Restful API，SOAP API和GraphQl API。

RESTFUL API

RESTful APIs遵守代表性状态转移的原则（REST）。 RESTFUL API使用HTTP请求与Web资源进行交互并表示资源为URL。这使得使用标准的HTTP动词易于操纵资源。

肥皂API

SOAP API，（简单对象访问协议）是用于通过网络交换基于XML的消息的协议。它使用一组来发送和接收消息的规则，通常用于企业级应用程序。

GraphQL API

GraphQL是一种较新的API技术，它提供了一种更灵活的请求数据的方法。它允许开发人员向服务器发送单个请求，并指定所需的确切数据。这可以帮助减少检索数据所需的请求数量，并可以提高性能。

为什么要记录API？

清晰简洁的文档对于任何API都是必不可少的。它可以改善采用和开发人员的经验，从而导致更快的开发时间和提高质量。
正确的API文档应包括API，其端点及其输入和输出参数的描述。它也应考虑到目标受众，并包括如何使用API​​以及可能返回的任何错误代码的示例。

介绍OpenAPI

OpenAPI以前被称为Swagger，此后已成为API文档的标准。 OpenAPI允许您使用JSON或YAML文件来定义API，并提供广泛的文档功能。

OpenAPI规范的关键组件包括：

• 信息：这提供了有关API的基本信息，包括其标题，版本和描述。

• 路径：路径定义API的不同端点，以及其输入和输出参数。

• 参数：这定义了每个端点的输入和输出参数，包括其数据类型和任何限制。

• 响应：这定义了API可以返回的不同响应，包括其状态代码和任何错误消息。

编写OpenAPI 3文档的最佳实践

现在，我们对OpenAPI有了基本的了解，让我们看一下如何使用它来记录API。编写文档并不是一件容易的事，但是OpenAPI提供了描述API的清晰且结构化的方法。一些最佳实践包括：

• 使用清晰简洁的语言：避免在预期受众可能不熟悉的技术术语上使用技术术语。

• 提供示例和用例：这可以帮助开发人员了解如何在现实世界中使用API​​。

• 使用格式和组织：使用标题，项目符号和其他格式选项使文档易于阅读和导航。

• 保持文档的最新状态：随着API的变化，文档也会更改。确保将其保持最新状态，以使其仍然是有用的资源。

在GO中使用OpenAPI 3记录API的示例

假设我们有一个API，允许用户检索有关书籍的信息。这是我们可以使用OpenAPI 3进行记录的方式：

• 包含GO API的main.go文件：

package main

import (
    "log"
    "net/http"
    "strconv"

    "github.com/go-chi/chi"
    "github.com/go-chi/chi/middleware"
    "github.com/go-chi/render"
)

type Book struct {
    ID     int    `json:"id"`
    Title  string `json:"title"`
    Author string `json:"author"`
}

var books = []Book{
    {1, "The Go Programming Language", "Alan A. A. Donovan, Brian W. Kernighan"},
    {2, "Designing Data-Intensive Applications", "Martin Kleppmann"},
    {3, "Code Complete", "Steve McConnell"},
}

func main() {
    r := chi.NewRouter()
    r.Use(middleware.Logger)
    r.Use(render.SetContentType(render.ContentTypeJSON))

    r.Get("/books/{id}", GetBook)

    log.Println("Starting server on :3000")
    http.ListenAndServe(":3000", r)
}

func GetBook(w http.ResponseWriter, r *http.Request) {
    bookID := chi.URLParam(r, "id")
    for _, book := range books {
        if strconv.Itoa(book.ID) == bookID {
            render.JSON(w, r, book)
            return
        }
    }
    render.Status(r, http.StatusNotFound)
}

• 这是使用OpenAPI 3标准记录API的相应book.yaml文件：

openapi: 3.0.0
info:
  title: Book API
  description: API for retrieving information about books
  version: 1.0.0
servers:
  - url: http://localhost:3000
    description: Local server
paths:
  /books/{id}:
    get:
      summary: Get a book by ID
      description: Returns a single book object by ID
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: ID of the book to retrieve
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
        '404':
          description: Book not found
          content: {}
components:
  schemas:
    Book:
      type: object
      required:
        - id
        - title
        - author
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the book
        title:
          type: string
          description: Title of the book
        author:
          type: string
          description: Author of the book

book.yaml文件定义了每个端点的API版本，基本URL和路径。它还指定了每个端点允许的HTTP方法，例如get，post，put，删除等。例如，GetBook端点在yaml文件中定义了以下详细信息：

  /books/{id}:
    get:
      summary: Retrieve a book by ID
      description: Retrieve the book with the given ID from the library.
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: Numeric ID of the book to retrieve.
      responses:
        '200':
          description: A book object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
        '404':
          description: The specified book was not found.

此定义指定端点是一种GET方法，可通过ID检索书籍。它还指定了端点接受的参数以及其返回的响应。在这种情况下，GetBook端点返回代表一本书的json对象，如果找不到指定书，则返回404错误。

book.yaml文件还包括API使用的数据模型的定义。例如，“书”对象定义如下：

components:
  schemas:
    Book:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        author:
          type: string
      required:
        - id
        - title
        - author

此定义指定Book对象是具有三个属性的对象：id，title和author。 id属性是整数，而title和author属性是字符串。它还指定了所有三个属性。

让我们分解上面的GO Book API的YAML文件规范的关键组件：

• openapi：指定使用的OpenAPI规范的版本。

• info：提供有关API的元数据，包括标题，说明，版本和联系信息。

• servers：定义服务器信息，包括URL和描述。

• paths：定义API的可用端点（路由），包括用于访问每个端点的HTTP方法，以及每个端点的请求和响应参数。

• components：定义可重复使用的模式，参数，响应和安全方案。

• security：定义用于保护API的安全方案以及端点需要授权。

• tags：提供有关API路径的元数据，包括简短说明和可选的外部文档链接。

• responses：定义API可以返回的可能响应，包括响应代码，描述和内容架构。

• requestBody：定义端点的Expecterd请求主体，包括内容类型和内容架构。

• parameters：定义可以在请求的路径，查询，标题或cookie中使用的参数，包括类型，描述和默认值。

• 200：此组件指定响应，当请求成功使用200。

我们创建了OpenAPI规范文件后，我们可以使用它以各种格式生成文档，例如HTML，PDF或Markdown。有许多工具可用于从OpenAPI规范中生成文档，例如Swagger UI，ReDoc和Slate。

通过在OpenAPI 3规范文件中定义API端点和数据模型，该文件提供了可用于生成代码，测试用例，客户端库，服务器存根和交互式API文档的API的全面文档。这不仅使开发人员更容易理解和使用API​​，而且从长远来看也可以节省时间和精力。

这只是如何使用OpenAPI在GO中记录API的一个示例。还有许多其他方法可以编写OpenAPI规格并将其集成到您的应用程序中。确切的方法可能会根据所记录的特定API和所需的输出格式而有所不同。

测试书API

要测试Go Book API并在本地运行，您可以按照以下步骤操作：

1. 在您的终端或代码编辑器中，导航到项目目录。

2. 运行go mod init <module_name>创建一个新的GO模块。

3. 运行命令go install github.com/go-chi/chi/v5以安装软件包。
   安装软件包后，您应该能够将其导入到GO代码中并使用其功能和方法。
   注意：Go version 1.18，不再使用go get命令安装软件包。相反，我们使用go install命令。

4. 然后我们运行main.go文件以启动服务器。按照上述程序之后，它将在port :3000

上列出。

5. 我们可以在端子上测试API，Postman或ReqBin。 （我使用了Reqbin，它是用于休息和肥皂API的在线API测试工具，直接从您的浏览器中工作。）

• 在终端中，我们可以使用cURL工具向API提出请求。 要向/books/1端点提出请求，请在您的终端中运行此命令：

curl http://localhost:3000/books/1

这应该返回包含一系列书籍的JSON响应。

• 要使用reqbin提出请求，请将请求方法设置为GET，然后将请求URL设置为http.//localhost:3000/books/1。然后，您可以发送请求并在“响应”选项卡中查看响应。

这是我使用ReqBin测试GO Book API的屏幕截图。
“洋红色”中突出显示的盒子是针对GET request URL的，而“红橙色”中突出显示的盒子是用于“响应”

记录API的工具

创建了API文档后，重要的是选择正确的工具将其展示给用户。有许多用于记录API的工具，每个工具都有其自己的优点和劣势。记录API的一些最受欢迎的工具包括：

• Swagger UI：Swagger UI是用于记录REST API的流行开源工具。它允许您使用OpenAPI为API创建交互式文档，并提供一个用于探索API的用户友好界面。

• Postman：Postman是一种流行的API开发环境，也可以用于API文档。它允许您使用Markdown为您的API创建文档，并提供一个用于探索API的用户友好界面。

• OpenAPI Generator：OpenAPI Generator是一个代码生成器，可以使用OpenAPI规范自动为API创建文档。该规范是用于描述RESTFUL API的标准化格式，这使得以一致且可预测的方式生成文档变得易于生成。 OpenAPI发电机支持广泛的编程语言，包括GO，Java，Python等。

• Readme：readme是一个流行的文档平台，可用于API文档。它提供了一个用于创建和发布API文档的用户友好界面，并支持OpenAPI和Swagger。

• ReDocly：重新计算是用于创建API文档的开源工具。它允许您使用OpenAPI为API创建文档，并提供用于探索API的用户友好界面。

选择用于记录API的工具时，重要的是要考虑您的特定需求和要求。要考虑的一些重要因素包括：

• 易用性：该工具是用户友好且易于导航的吗？用户可以轻松找到所需的信息吗？

• 自定义：您可以自定义文档的外观和感觉以匹配您的品牌吗？

• 集成：工具可以与其他工具和平台集成，例如GitHub，Jira或Slack？

• 协作：该工具是否允许团队成员之间的协作，例如评论或版本控制？

• 可伸缩性：随着API的成长和发展，刀具可以扩展吗？

无论您选择哪种工具，都要花费时间和精力来创建良好的API文档，这是值得的，从长远来看将有所回报。

结论

记录API是软件开发的重要组成部分，OpenAPI提供了一种强大而灵活的方法来创建清晰而简洁的API文档。通过遵循编写文档和使用API​​文档工具的最佳实践，您可以使其他开发人员更容易获得API并改善其整体体验。随着宁静API的日益普及和API经济的增长，投入时间和资源来创建高质量的API文档比以往任何时候都重要。

我希望本文为API文档和OpenAPI提供了有用的介绍，以及有关如何使用OpenAPI 3规格在GO中记录API的实用提示和示例。通过遵循这些准则和最佳实践，您可以创建有据可查，易于使用且更广泛地采用的API。

可以随意联系，或在下面的评论部分中放下问题。

我们也可以在LinkedIn和Twitter上连接。
愉快的编码！ ð�ð»ð

pikisuperstar的图像在Freepik上