OpenAPI Options

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

Overview

json

{
  "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:

json

{
  "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:

json

{
  "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

json

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

Basic Authentication

json

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

json

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

API Key in Header

json

{
  "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:

json

{
  "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

json

{
  "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:

json

{
  "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.

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

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.

json

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

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

openapi annotation - Per-routine @openapi hide / @openapi tag <name> overrides
tags annotation - Tag endpoints for OpenAPI grouping
Comment Annotations Guide - How annotations work
Configuration Guide - How configuration works

Next Steps

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

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 ​

Comments

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