OpenAPI或swagger.json自动发现

Question

是否有规范或惯例要求在URL中放置swagger.json（或者其他已经约定好的名称），以便公共API可以自动发现我的网站？

- anatoly techtonik

---

据我所知，没有这样的功能。我建议您通过https://github.com/OAI/OpenAPI-Specification/issues提交您的建议，因为这个规范对于OpenAPI/Swagger生态系统非常有用。 - William Cheng

@wing328，已完成 - https://github.com/OAI/OpenAPI-Specification/issues/864 - anatoly techtonik

Answer 1

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

原始答案：

OpenAPI Wiki 建议至少在服务器API中使用/api-docs端点。我已经在很多网站上看到过这种用法，而且这也是我们公司的标准。

希望能有所帮助。

- Jeff Dickey

---

@anatolytechtonik 谢谢。我认错了，会修改答案的。 - Jeff Dickey

现在看起来不错。但是...它仍然没有给出答案，一个人应该把这些文件放在哪里并知道从哪里阅读它们？ - anatoly techtonik

Answer 2

如何在收到 URL / 的 OPTIONS 请求时，在 HTTP 响应主体中提供 Swagger JSON？

这是 相关的 RFC 明确允许的。

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

- AnotherSmellyGeek

Answer 3

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

1. https://example.com/.well-known/schema-discovery is a JSON document pointing to array of available schemas:

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

2. If there is only one version of API, then https://example.com/openapi.json should be enough.

3. HTTP Headers. I remember somebody from Google proposed HTTP header for pointing to API. If you can find or remember it, please tell me.

- anatoly techtonik