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 规范文档
获取您的副本！