Swagger 框架有助于为 API 定义一种与语言无关、人类可读的格式，从而简化实施、推动采用并稳定开发。
生成 API 的 Swagger 规范通常遵循两个过程
- 运行时 Swagger 生成： 在这种方法中，Swagger 契约是从 API 生成的，基于针对各种资源、方法和控制器添加的元数据。此元数据将在运行时生成 Swagger 契约、客户端代码和其他工件。通常，此元数据将以代码注释的形式存在。当针对其资源调用各种方法和函数时，这些工具会触发，并根据 API 中定义的元数据生成 Swagger 契约。
- 构建时 Swagger 生成： 在这种方法中，Swagger 契约是在预处理 API 时生成的，即在运行时之前。API 中针对各种资源、方法和函数的注释有助于生成 Swagger 规范。这些注释通常采用预定义的特殊语法，具体取决于您用于生成契约的工具类型。该工具会扫描您的 API 代码中的这些特殊注释，并生成 Swagger 契约作为输出。
这两种方法都有其优缺点。在运行时生成 Swagger 规范会从代码中生成更准确的 API 契约，但代价是软件负载（以其他依赖项的形式）、开发时间，并且可能会给系统增加一些开销。相反，在 API 运行时之前生成 Swagger 契约是一个更轻量级的过程，但很有可能生成的 Swagger 契约可能无法准确描述您的 API，因为它必须手动维护。
SwaggerHub 团队最近发布了一个免费资源 — 使用 Swagger 为现有 API 编写文档 — 探讨这两种为您的 API 生成 Swagger 的方法。
您将学习
- API 文档的重要性
- 为什么使用 Swagger 进行文档编写
- 将 Swagger 添加到 API 的方法
- 记录您的 Swagger 规范
获取您的副本！