Skip to content

OpenAPI configuration

Every OpenApiConfig field — the switch, the whole info block, and the committed copy of the document — set from the environment or pinned in code.

OpenApiConfig holds the document’s info block, the switch that serves it, and where a committed copy is written. The block names your app after its binary by default — the package name, version and description #[nest_rs::main] reads off its Cargo.toml — so a release bumps the document’s version with the crate’s. Every field is on the framework-wide dual path — the .env cascade and the pinned struct:

Terminal window
$ NESTRS_OPENAPI__TITLE="Publish API" \
NESTRS_OPENAPI__VERSION="2.1.0" \
NESTRS_OPENAPI__LICENSE_NAME="Apache 2.0" \
NESTRS_OPENAPI__LICENSE_IDENTIFIER="Apache-2.0" \
nestrs run dev api
FieldEnv varDefaultEffect
enabled<PREFIX>_OPENAPI__ENABLEDSurface::ByProfile: open in declared dev/test onlyServes /api and /api-json. Opened outside a dev profile, the boot logs a warn — the document and the UI are public.
title<PREFIX>_OPENAPI__TITLEthe binary’s package nameinfo.title.
version<PREFIX>_OPENAPI__VERSIONthe binary’s package versioninfo.version — your API’s version, not the framework’s.
summary<PREFIX>_OPENAPI__SUMMARYnoneinfo.summary, one line.
description<PREFIX>_OPENAPI__DESCRIPTIONthe binary’s package description, if its manifest has oneinfo.description.
terms_of_service<PREFIX>_OPENAPI__TERMS_OF_SERVICEnoneinfo.termsOfService, a URL.
contact<PREFIX>_OPENAPI__CONTACT_NAME, __CONTACT_URL, __CONTACT_EMAILnoneinfo.contact; any one key makes it.
license<PREFIX>_OPENAPI__LICENSE_NAME, __LICENSE_IDENTIFIER, __LICENSE_URLnoneinfo.license: the name, then an SPDX identifier or a URL — both is a boot error, as OpenAPI 3.1 makes them exclusive, and either without a name is one too.
emit<PREFIX>_OPENAPI__EMITSurface::ByProfile: open in declared dev onlyWrites the document /api-json serves to emit_path once at boot — the committed copy a pull request diffs. Off under test, so parallel suites never rewrite it. With enabled closed no document is built: nothing is written, and the boot says so at warn.
emit_path<PREFIX>_OPENAPI__EMIT_PATHopenapi.jsonWhere emit writes; a relative path is the app crate’s — the one #[nest_rs::main] expanded in — whatever directory the process runs from.

Pass an OpenApiConfig at the import site instead of reading the environment:

apps/api/src/module.rs
use nest_rs::openapi::{OpenApiConfig, OpenApiLicense, OpenApiModule};
OpenApiModule::for_root(OpenApiConfig {
title: "Publish API".into(),
version: "2.1.0".into(),
license: Some(OpenApiLicense::new("Apache 2.0").with_identifier("Apache-2.0")),
..Default::default()
})

The pinned struct is the base <PREFIX>_OPENAPI__* overlays, field by field — so the deployment can still override any one of them, a single contact or license key included. See the precedence chain.

enabled and emit are Surfaces, left to the profile by ..Default::default(), so the documentation stays a development surface: served when the process declares development or test, closed elsewhere — a process that declares no <PREFIX>_ENV included — until enabled: Surface::Open in the pin or <PREFIX>_OPENAPI__ENABLED=true in the deployment opens it, a visible line, logged at warn outside a development or test profile. A document written there, with emit opened beside it, is said at warn too.

A development run rewrites the file beside the app’s Cargo.toml — the profile opens emit, with nothing to set — and a pull request shows each change to the API contract as a diff of it. Pin it with a test that compares what the app serves to what is committed, as the demo’s api app does — the suite then fails the day someone forgets to rerun:

apps/api/tests/e2e/openapi.rs (from the demo, abridged)
#[tokio::test]
async fn the_committed_document_is_the_one_the_app_serves() {
let app = boot().await;
let served = served_document(&app).await;
let path = concat!(env!("CARGO_MANIFEST_DIR"), "/openapi.json");
// …
assert!(
served == committed,
// …
);
}