Appearance

@json-express/docs-swagger ​

Official Swagger OpenAPI documentation generator for JSONExpress.

The @json-express/docs-swagger package analyzes your declarative JSONExpress ModelSchema objects and dynamically generates a fully interactive OpenAPI (Swagger v3) UI.

Because the Swagger documentation is compiled directly from the schema engine, your API documentation is guaranteed to be 100% accurate and can never drift from your actual code.

Installation ​

bash
npm install @json-express/docs-swagger

Configuration ​

The Swagger provider is auto-discovered by the json-express runtime. Installing it replaces the docs-light provider that ships with @json-express/boot.

bash
npm uninstall @json-express/docs-light
npm install @json-express/docs-swagger
npx json-express

By default the interactive Swagger UI mounts at GET /docs. Branding lives under jex.swagger.* in your config provider:

bash
# .env
jex.swagger.path=/api/explorer
jex.swagger.title=My Enterprise API
jex.swagger.version=2.0.0
jex.swagger.description=Internal documentation for the core services.

If both docs-light and docs-swagger are installed, pick one explicitly:

bash
jex.docs=@json-express/docs-swagger

Core Features ​

1. Dynamic OpenAPI v3 Compilation ​

The plugin iterates through every single model defined in your project. It maps JSONExpress schema types (types.string(), types.number()) directly to OpenAPI specification data types.

It automatically documents the expected request bodies for POST and PATCH endpoints, and documents the standard JSON response payloads for GET requests.

2. Auto-Documented Query Parameters ​

If you are using the @json-express/api-rest generator, your endpoints automatically support complex query strings. The Swagger plugin injects documentation for these parameters (such as _expand, _embed, _page, and _limit) directly into the UI so API consumers know exactly how to use them.

3. Access Control Awareness ​

Because Swagger is integrated directly into the schema engine, it respects your field-level access rules. If a field is marked as access: { read: false } (like a passwordHash), the Swagger UI will completely omit that field from the "Response Example" payloads, ensuring you do not accidentally document internal security fields.