openapi.md

outline

2

3

title

OpenAPI Configuration

titleTemplate

NpgsqlRest

description

Generate OpenAPI/Swagger specifications for your PostgreSQL REST API. Configure document title, version, servers, and security schemes for API documentation.

head

meta

name	content
keywords	npgsqlrest openapi, postgresql swagger, api documentation, openapi specification, rest api docs, swagger postgresql

meta

property	content
og:title	NpgsqlRest OpenAPI Configuration

meta

property	content
og:description	Generate OpenAPI/Swagger specifications for your PostgreSQL REST API with customizable documentation.

meta

property	content
og:type	article

OpenAPI Options

Configuration for generating OpenAPI specification files and endpoints for NpgsqlRest APIs.

Overview

{
  "NpgsqlRest": {
    "OpenApiOptions": {
      "Enabled": false,
      "FileName": "npgsqlrest_openapi.json",
      "UrlPath": "/openapi.json",
      "FileOverwrite": true,
      "DocumentTitle": null,
      "DocumentVersion": "1.0.0",
      "DocumentDescription": null,
      "AddCurrentServer": true,
      "Servers": [],
      "SecuritySchemes": [],
      "IncludeSchemas": [],
      "ExcludeSchemas": [],
      "NameSimilarTo": null,
      "NameNotSimilarTo": null,
      "RequiresAuthorizationOnly": false,
      "OmitAutomaticParameters": false
    }
  }
}

Settings Reference

Setting	Type	Default	Description
`Enabled`	bool	`false`	Enable OpenAPI generation.
`FileName`	string	`"npgsqlrest_openapi.json"`	File name for generated OpenAPI file. `null` to skip file generation.
`UrlPath`	string	`"/openapi.json"`	URL path for OpenAPI endpoint. `null` to skip endpoint generation.
`FileOverwrite`	bool	`true`	Overwrite existing files.
`DocumentTitle`	string	`null`	API title in the `info` section. Uses database name if `null`.
`DocumentVersion`	string	`"1.0.0"`	API version in the `info` section.
`DocumentDescription`	string	`null`	API description in the `info` section.
`AddCurrentServer`	bool	`true`	Include current server in the `servers` section.
`Servers`	array	`[]`	Additional server entries for the `servers` section.
`SecuritySchemes`	array	`[]`	Security schemes for authentication documentation.
`IncludeSchemas`	string[]	`[]`	Schema allow-list. When non-empty, only endpoints whose routine schema appears here are documented.
`ExcludeSchemas`	string[]	`[]`	Schema deny-list. Applied alongside `IncludeSchemas`.
`NameSimilarTo`	string	`null`	PostgreSQL `SIMILAR TO` pattern matched against routine names (anchored). When set, only matching routines are documented.
`NameNotSimilarTo`	string	`null`	PostgreSQL `SIMILAR TO` pattern for exclusion. Applied alongside `NameSimilarTo`.
`RequiresAuthorizationOnly`	bool	`false`	When `true`, document only endpoints that require authorization — health, login, and other anonymous probes drop out.
`OmitAutomaticParameters`	bool	`false`	When `true`, omit server-filled parameters from documented query parameters and request bodies. See Omitting automatic parameters.

Document Info

Configure the OpenAPI document metadata:

{
  "NpgsqlRest": {
    "OpenApiOptions": {
      "Enabled": true,
      "DocumentTitle": "My API",
      "DocumentVersion": "2.0.0",
      "DocumentDescription": "REST API for my application"
    }
  }
}

Servers

Add server entries to the OpenAPI specification:

{
  "NpgsqlRest": {
    "OpenApiOptions": {
      "AddCurrentServer": true,
      "Servers": [
        {
          "Url": "https://api.example.com",
          "Description": "Production server"
        },
        {
          "Url": "https://staging-api.example.com",
          "Description": "Staging server"
        }
      ]
    }
  }
}

Security Schemes

Define authentication schemes for the OpenAPI document. Supported types:

Http - For Bearer and Basic authentication
ApiKey - For Cookie, Header, or Query parameter authentication

Bearer Token Authentication

{
  "SecuritySchemes": [
    {
      "Name": "bearerAuth",
      "Type": "Http",
      "Scheme": "Bearer",
      "BearerFormat": "JWT",
      "Description": "JWT Bearer token authentication"
    }
  ]
}

Basic Authentication

{
  "SecuritySchemes": [
    {
      "Name": "basicAuth",
      "Type": "Http",
      "Scheme": "Basic",
      "Description": "HTTP Basic authentication"
    }
  ]
}

Cookie Authentication

{
  "SecuritySchemes": [
    {
      "Name": "cookieAuth",
      "Type": "ApiKey",
      "In": ".AspNetCore.Cookies",
      "ApiKeyLocation": "Cookie",
      "Description": "Cookie-based authentication"
    }
  ]
}

API Key in Header

{
  "SecuritySchemes": [
    {
      "Name": "apiKeyAuth",
      "Type": "ApiKey",
      "In": "X-API-Key",
      "ApiKeyLocation": "Header",
      "Description": "API key in header"
    }
  ]
}

Security Scheme Settings

Setting	Type	Description
`Name`	string	Unique scheme identifier.
`Type`	string	Scheme type: `"Http"` or `"ApiKey"`.
`Scheme`	string	HTTP auth scheme (`"Bearer"`, `"Basic"`). For `Type: "Http"` only.
`BearerFormat`	string	Bearer token format (e.g., `"JWT"`). Optional.
`In`	string	Cookie/header/query name. For `Type: "ApiKey"` only.
`ApiKeyLocation`	string	Location: `"Cookie"`, `"Header"`, or `"Query"`. For `Type: "ApiKey"` only.
`Description`	string	Description of the security scheme.

Complete Example

Production configuration with multiple security schemes:

{
  "NpgsqlRest": {
    "OpenApiOptions": {
      "Enabled": true,
      "FileName": "openapi.json",
      "UrlPath": "/openapi.json",
      "FileOverwrite": true,
      "DocumentTitle": "My REST API",
      "DocumentVersion": "1.0.0",
      "DocumentDescription": "REST API generated from PostgreSQL functions",
      "AddCurrentServer": true,
      "Servers": [
        {
          "Url": "https://api.example.com",
          "Description": "Production server"
        }
      ],
      "SecuritySchemes": [
        {
          "Name": "bearerAuth",
          "Type": "Http",
          "Scheme": "Bearer",
          "BearerFormat": "JWT",
          "Description": "JWT Bearer token authentication"
        },
        {
          "Name": "cookieAuth",
          "Type": "ApiKey",
          "In": ".AspNetCore.Cookies",
          "ApiKeyLocation": "Cookie",
          "Description": "Cookie-based authentication"
        }
      ]
    }
  }
}

Filters (New in 3.15.0)

Five config keys (and a per-routine @openapi comment annotation) control which endpoints appear in the generated document. The HTTP endpoints themselves are unaffected — only their inclusion in the spec is. Defaults are "no filter", so existing configs see no change.

Schema and name filters

{
  "NpgsqlRest": {
    "OpenApiOptions": {
      "Enabled": true,
      "IncludeSchemas": ["partner"],
      "ExcludeSchemas": ["internal"],
      "NameSimilarTo": "partner_%",
      "NameNotSimilarTo": "%_admin",
      "RequiresAuthorizationOnly": true
    }
  }
}

NameSimilarTo / NameNotSimilarTo use PostgreSQL SIMILAR TO syntax — _ matches one char, % matches any sequence; |, *, +, ?, (...), [...] work via regex translation. Anchored (the pattern must cover the entire routine name).
All filters are conjunctive — an endpoint must pass every one to be documented.

Filter order

Filters are applied in this order; the first rejection short-circuits the rest:

@openapi hide annotation (per-routine wins over everything)
RequiresAuthorizationOnly vs. the endpoint's authorization requirement
IncludeSchemas membership
ExcludeSchemas membership
NameSimilarTo match
NameNotSimilarTo match (negative)

Partner-facing document example

A full "host serves one API, partner-only OpenAPI document" config:

{
  "NpgsqlRest": {
    "OpenApiOptions": {
      "Enabled": true,
      "FileName": "openapi-partner.json",
      "UrlPath": "/openapi/partner.json",
      "DocumentTitle": "Acme Partner API",
      "DocumentDescription": "JWT-authenticated REST surface for partner integrations.",

      "IncludeSchemas": ["partner"],
      "RequiresAuthorizationOnly": true,
      "NameNotSimilarTo": "%_admin",

      "SecuritySchemes": [
        { "Name": "bearerAuth", "Type": "Http", "Scheme": "Bearer", "BearerFormat": "JWT" }
      ],
      "Servers": [
        { "Url": "https://api.acme.com", "Description": "Production" }
      ]
    }
  }
}

The internal cookie-authenticated surface stays reachable on the same host — only the document is partner-scoped.

::: warning One document per process Only one OpenAPI document is generated per host. To serve both a partner and an internal spec, run two NpgsqlRest hosts with different filter configs, or filter to a single audience. :::

Omitting Automatic Parameters

::: tip New in 3.18.2 OmitAutomaticParameters was added in 3.18.2 (also available on the Code Generation and HTTP File generators). Default is false, so the generated document is unchanged unless you opt in. :::

Some parameters are filled by the server and a client value would simply be ignored — documenting them as settable is misleading. When OmitAutomaticParameters is true, such a parameter is left out of the generated document (query parameters and request body) when it is automatic and optional. "Automatic" covers:

HTTP Custom Type fields,
resolved-parameter expressions,
upload-metadata parameters,
and — on endpoints that use user parameters — IP-address and user-claim parameters.

{
  "NpgsqlRest": {
    "OpenApiOptions": {
      "Enabled": true,
      "OmitAutomaticParameters": true
    }
  }
}

When every parameter of an endpoint is omitted, the operation is documented with no parameters and no requestBody.

Next Steps

HTTP Files - Configure HTTP file generation
NpgsqlRest Options - Configure general NpgsqlRest settings

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

OpenAPI Options

Overview

Settings Reference

Document Info

Servers

Security Schemes

Bearer Token Authentication

Basic Authentication

Cookie Authentication

API Key in Header

Security Scheme Settings

Complete Example

Filters (New in 3.15.0)

Schema and name filters

Filter order

Partner-facing document example

Omitting Automatic Parameters

Related

Next Steps

Uh oh!

FilesExpand file tree

openapi.md

Latest commit

History

openapi.md

File metadata and controls

OpenAPI Options

Overview

Settings Reference

Document Info

Servers

Security Schemes

Bearer Token Authentication

Basic Authentication

Cookie Authentication

API Key in Header

Security Scheme Settings

Complete Example

Filters (New in 3.15.0)

Schema and name filters

Filter order

Partner-facing document example

Omitting Automatic Parameters

Related

Next Steps