Skip to content

Commit b6062c1

Browse files
Merge pull request #3206 from mag123c/docs(swagger)optional-json-yaml-raws
docs(swagger): add ui/raws description, hint
2 parents b0b8d77 + 86957d0 commit b6062c1

File tree

1 file changed

+32
-2
lines changed

1 file changed

+32
-2
lines changed

content/openapi/introduction.md

Lines changed: 32 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -174,12 +174,29 @@ export interface SwaggerCustomOptions {
174174
useGlobalPrefix?: boolean;
175175
176176
/**
177-
* If `false`, only API definitions (JSON and YAML) will be served (on `/{path}-json` and `/{path}-yaml`).
178-
* This is particularly useful if you are already hosting a Swagger UI somewhere else and just want to serve API definitions.
177+
* If `false`, the Swagger UI will not be served. Only API definitions (JSON and YAML)
178+
* will be accessible (on `/{path}-json` and `/{path}-yaml`). To fully disable both the Swagger UI and API definitions, use `raw: false`.
179179
* Default: `true`.
180+
* @deprecated Use `ui` instead.
180181
*/
181182
swaggerUiEnabled?: boolean;
182183
184+
/**
185+
* If `false`, the Swagger UI will not be served. Only API definitions (JSON and YAML)
186+
* will be accessible (on `/{path}-json` and `/{path}-yaml`). To fully disable both the Swagger UI and API definitions, use `raw: false`.
187+
* Default: `true`.
188+
*/
189+
ui?: boolean;
190+
191+
/**
192+
* If `true`, raw definitions for all formats will be served.
193+
* Alternatively, you can pass an array to specify the formats to be served, e.g., `raw: ['json']` to serve only JSON definitions.
194+
* If omitted or set to an empty array, no definitions (JSON or YAML) will be served.
195+
* Use this option to control the availability of Swagger-related endpoints.
196+
* Default: `true`.
197+
*/
198+
raw?: boolean | Array<'json' | 'yaml'>;
199+
183200
/**
184201
* Url point the API definition to load in Swagger UI.
185202
*/
@@ -270,6 +287,19 @@ export interface SwaggerCustomOptions {
270287
271288
}
272289
```
290+
> info **Hint** `ui` and `raw` are independent options. Disabling Swagger UI (`ui: false`) does not disable API definitions (JSON/YAML). Conversely, disabling API definitions (`raw: []`) does not disable the Swagger UI.
291+
>
292+
> For example, the following configuration will disable the Swagger UI but still allow access to API definitions:
293+
> ```typescript
294+
>const options: SwaggerCustomOptions = {
295+
> ui: false, // Swagger UI is disabled
296+
> raw: ['json'], // JSON API definition is still accessible (YAML is disabled)
297+
>};
298+
>SwaggerModule.setup('api', app, options);
299+
> ```
300+
>
301+
> In this case, http://localhost:3000/api-json will still be accessible, but http://localhost:3000/api (Swagger UI) will not.
302+
273303
274304
#### Example
275305

0 commit comments

Comments
 (0)