使用 OpenAPI 3 标准编写 Go API 文档：实用指南

什么是API？

为什么需要文档 API？

API文档工具

结论

由 Mux 主办的 DEV 全球展示挑战赛：展示你的项目！

API 已成为现代软件开发不可或缺的一部分，它使应用程序能够相互通信和交换数据。然而，构建 API 仅仅是成功的一半。如果没有完善的文档，开发人员可能难以理解如何使用 API，从而导致时间和资源的浪费。这就是 API 文档的作用所在。

OpenAPI是一个广泛使用的 RESTful API 描述规范。凭借其强大的模式和文档功能，它现在已成为API 文档的事实标准。在本文中，我们将探讨 API 文档的重要性，介绍 OpenAPI，并提供使用 Go 编写 OpenAPI 文档的示例。

让我们开始吧！

什么是API？

应用程序编程接口（API）是一组用于构建软件应用程序的协议、例程和工具。API 允许不同的应用程序相互通信，从而简化数据和功能的共享。API 可以采用多种形式，包括 RESTful API、SOAP API 和 GraphQL API。

RESTful API

RESTful API遵循表述性状态转移 (REST) 原则。RESTful API 使用 HTTP 请求与 Web 资源交互，并将资源表示为 URL。这使得使用标准的 HTTP 动词（例如 GET、POST、PUT 和 DELETE）来操作资源变得非常容易。

SOAP API

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

GraphQL API

GraphQL是一种较新的 API 技术，它提供了一种更灵活的数据请求方式。开发者只需向服务器发送一个请求，即可精确指定所需的数据。这有助于减少检索数据所需的请求次数，从而提高性能。

为什么需要文档 API？

清晰简洁的文档对于任何 API 都至关重要。它可以提高 API 的普及率和开发者体验，从而加快开发速度并提升产品质量。
完善的 API 文档应包含 API 的描述、端点以及输入输出参数。此外，文档编写时应充分考虑目标受众，并提供 API 使用示例以及可能返回的错误代码。

介绍 OpenAPI

OpenAPI前身为 Swagger，现已成为 API 文档的标准。OpenAPI 允许您使用 .xmlJSON文件定义 API YAML，并提供丰富的文档功能。

OpenAPI规范的关键组成部分包括：

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

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

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

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

编写 OpenAPI 3 文档的最佳实践

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

• 使用清晰简洁的语言：避免使用目标受众可能不熟悉的专业术语。

• 提供示例和用例：这有助于开发人员了解如何在实际场景中使用 API。

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

• 保持文档更新：随着 API 的变更，文档也应随之更新。务必确保文档保持最新状态，使其成为有用的参考资料。

使用 Go 语言编写 OpenAPI 3 API 文档的示例

假设我们有一个 API，允许用户检索书籍信息。以下是如何使用 OpenAPI 3 为其编写文档：

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

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)
}

• 以下是book.yaml使用 OpenAPI 3 标准编写的 API 文档对应的文件：

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、DELETE 等。例如，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 使用的数据模型定义。例如，“Book”对象定义如下：

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

此定义明确指出，该Book对象是一个具有三个属性的对象：id`a`、title`b` 和author`c`。`a`id属性为整数，而 `b`title和 ` authorc` 属性为字符串。它还明确指出，所有三个属性都是必需的。

YAML让我们来分解一下上面 Go 书籍 API 文件规范的关键组成部分：

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

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

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

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

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

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

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

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

• requestBody：定义端点的预期请求正文，包括内容类型和内容架构。

• 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 版本 1.18不再使用该go get命令安装软件包。现在，我们使用另一个go install命令。

4. 然后我们运行该main.go文件来启动服务器。按照上面的程序操作，它将在端口上列出。:3000

5. 然后我们可以在终端、 Postman或ReqBin上测试 API 。（我使用的是 ReqBin，它是一个用于 REST 和 SOAP API 的在线 API 测试工具，可以直接在浏览器中使用。）

• 在终端中，我们可以使用该cURL工具向 API 发送请求。要向端点发送请求/books/1，请在终端中运行以下命令：

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

应该返回一个包含书籍数组的 JSON 响应。

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

这是我使用ReqBin测试 Go 图书 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 生成器：OpenAPI 生成器是一个代码生成器，它可以使用 OpenAPI 规范自动为您的 API 创建文档。该规范是描述 RESTful API 的标准化格式，可以轻松生成一致且可预测的文档。OpenAPI 生成器支持多种编程语言，包括 Go、Java、Python 等。

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

• ReDocly：ReDocly 是一款用于创建 API 文档的开源工具。它允许您使用 OpenAPI 为您的 API 创建文档，并提供一个用户友好的界面来浏览您的 API。

在选择 API 文档编写工具时，务必考虑您的具体需求。以下是一些需要考虑的重要因素：

• 易用性：该工具是否用户友好且易于操作？用户能否轻松找到所需信息？

• 定制化：您能否定制文档的外观和风格，使其与您的品牌相符？

• 集成：该工具能否与其他工具和平台集成，例如GitHub、Jira或Slack？

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

• 可扩展性：随着 API 的增长和发展，该工具能否随之扩展？

无论你选择什么工具，投入时间和精力来创建良好的 API 文档都是非常值得的，并且从长远来看会有回报。

结论

API 文档编写是软件开发的重要组成部分，而 OpenAPI 提供了一种强大而灵活的方式来创建清晰简洁的 API 文档。遵循最佳实践并使用 API 文档工具，您可以让其他开发者更容易地访问您的 API，并提升他们的整体体验。随着 RESTful API 的日益普及和 API 经济的蓬勃发展，投入时间和资源来创建高质量的 API 文档比以往任何时候都更加重要。

我希望本文能为读者提供关于 API 文档和 OpenAPI 的实用入门知识，并提供一些关于如何使用 OpenAPI 3 规范在 Go 语言中编写 API 文档的实用技巧和示例。遵循这些指南和最佳实践，您可以创建文档完善、易于使用且更容易被其他开发者采用的 API。

欢迎随时联系我们，或在下方评论区留言提问。

我们也可以在LinkedIn和Twitter上联系。
祝您编程愉快！👨‍💻🚀

你可以请我喝杯咖啡/买本书来支持我:)

图片来自Freepik上的pikisuperstar