OpenAPI

PostgREST自动提供完整的 OpenAPI 有关根路径的说明。这提供了所有端点(表、外部表、视图、函数)的列表，以及支持的HTTP谓词和示例有效负载。

备注

默认情况下，此输出取决于JWT角色声明中包含的角色的权限(或 DB-anon-角色 如果没有发送JWT)。如果需要显示所有终结点，而不考虑角色的权限，请设置 Openapi-模式 配置到 ignore-privileges 。

对于额外的定制，OpenAPI输出包含每个 SQL comment 在任何数据库对象上。例如,

COMMENT ON SCHEMA mammals IS
  'A warm-blooded vertebrate animal of a class that is distinguished by the secretion of milk by females for the nourishment of the young';

COMMENT ON TABLE monotremes IS
  'Freakish mammals lay the best eggs for breakfast';

COMMENT ON COLUMN monotremes.has_venomous_claw IS
  'Sometimes breakfast is not worth it';

这些令人不快的注释将作为字段出现在生成的JSON中， info.description ， definitions.monotremes.description 和 definitions.monotremes.properties.has_venomous_claw.description 。

另外，如果您希望生成一个 summary 字段您可以通过使用多行注释来执行此操作， summary 将是第一行，而 description 它后面的几行：

COMMENT ON TABLE entities IS
  $$Entities summary

  Entities description that
  spans
  multiple lines$$;

同样，您可以通过对模式进行注释来覆盖API标题。

COMMENT ON SCHEMA api IS
$$FooBar API

A RESTful API that serves FooBar data.$$;

如果您需要包括 security 和 securityDefinitions 选项，请设置 Openapi-安全-活动 配置到 true 。

您可以使用如下工具 Swagger UI 根据描述创建精美的文档，并托管基于Web的交互式仪表板。该仪表板允许开发人员针对活动的PostgREST服务器发出请求，并提供请求头和示例请求正文的指导。

重要

当模式在运行的服务器下发生更改时，OpenAPI信息可能会过时。看见 架构缓存重新加载 。

覆盖完整的OpenAPI响应

您可以用函数结果覆盖整个默认响应。要执行此操作，请将该函数设置为 数据库根规范 。

db-root-spec = "root"

create or replace function root() returns json as $_$
declare
openapi json = $$
  {
    "swagger": "2.0",
    "info":{
      "title":"Overridden",
      "description":"This is a my own API"
    }
  }
$$;
begin
  return openapi;
end
$_$ language plpgsql;

curl http://localhost:3000

HTTP/1.1 200 OK

{
  "swagger": "2.0",
  "info":{
    "title":"Overridden",
    "description":"This is a my own API"
  }
}