OpenAPI 或 swagger.json 自动发现答案

【问题标题】：OpenAPI or swagger.json auto discoveryOpenAPI 或 swagger.json 自动发现
【发布时间】：2017-01-15 11:38:14
【问题描述】：

是否有任何关于 URL 的规范或约定，应该放置 swagger.json（或任何约定的名称）以便可以自动发现我网站的公共 API？

【问题讨论】：

我不知道。我建议您通过 github.com/OAI/OpenAPI-Specification/issues 提交您的建议，因为该约定将对 OpenAPI/Swagger 生态系统有用。
@wing328，完成 - github.com/OAI/OpenAPI-Specification/issues/864

【解决方案1】：

2017 年 4 月 19 日更新：我之前给出的 OpenAPI Wiki 答案是 "for a very very very old version of the spec"。同一来源指出，对于 2.0，标准是 swagger.json，对于 3.0，它更改为 openapi.json。

原答案：

OpenAPI Wiki recommends 使用 /api-docs 端点，位于至少对于服务器 API。我在野外看到了几个使用那是我们商店的标准。

希望对您有所帮助。

【讨论】：

@anatolytechtonik 谢谢。我的立场是正确的；将编辑答案。
现在看起来不错。 =) 但是.. 它仍然没有给出答案，应该将这些文件放在哪里并知道从哪里读取它们？

【解决方案2】：

如何在 HTTP 响应正文中提供 Swagger JSON，以响应对 URL / 的 OPTIONS 请求？

relevant RFC 明确允许这样做。

此外，考虑实施 HATEOAS，如 strongly advocated by Roy Fielding。

【讨论】：

【解决方案3】：

好的。 OpenAPI 3.0 仍然缺乏自动发现机制，我尝试提出一个基于 some things 的方案，该方案已经在运行：

https://example.com/.well-known/schema-discovery 是一个 JSON 文档，指向 array 的可用模式：

[
  {
    "schema_url": "/openapi.json",
    "schema_type": "openapi-3.0"
  },
  {
    "schema_url": "/v2/openapi.json",
    "schema_type": "openapi-3.0"
  }
]

如果API只有一个版本，那么https://example.com/openapi.json就足够了。
HTTP 标头。我记得 Google 的某个人提出了指向 API 的 HTTP 标头。如果你能找到或记得它，请告诉我。

【讨论】：