api - OpenAPI 或 swagger.json 自动发现

Question

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

Answer 1

2017 年 4 月 19 日更新：我之前给出的 OpenAPI Wiki 答案是“对于规范的非常非常老的版本”。同一消息来源指出，对于 2.0，标准是swagger.json，对于 3.0，它更改为openapi.json.

原答案：

OpenAPI Wiki建议使用/api-docs端点，至少对于服务器 API。我在野外看到过几个使用它的网站，这是我们的商店标准。

希望有帮助。

Answer 2

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

这是相关 RFC明确允许的。

此外，考虑实施 HATEOAS，正如Roy Fielding 强烈提倡的那样。

Answer 3

好的。OpenAPI 3.0 仍然缺乏自动发现机制，我尝试基于一些已经工作的东西提出一个方案：

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

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

2. 如果只有一个版本的 API，那么https://example.com/openapi.json应该就足够了。

3. HTTP 标头。我记得 Google 的某个人提出了指向 API 的 HTTP 标头。如果你能找到或记得它，请告诉我。