nitro/src/types/openapi.ts at c712ee1d4a9004195c00acf03a4d8223a96f15da · nitrojs/nitro · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
// import type { ApiReferenceConfiguration as ScalarConfig } from "@scalar/api-reference";

/**
 * Swagger UI configuration options.
 *
 * @see https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
 */
export interface SwaggerUIConfig {
  deepLinking?: boolean;
  displayOperationId?: boolean;
  defaultModelsExpandDepth?: number;
  defaultModelExpandDepth?: number;
  defaultModelRendering?: "example" | "model";
  displayRequestDuration?: boolean;
  docExpansion?: "list" | "full" | "none";
  filter?: boolean | string;
  persistAuthorization?: boolean;
  requestSnippetsEnabled?: boolean;
  showExtensions?: boolean;
  showCommonExtensions?: boolean;
  /** Only "alpha" is supported (function values are not JSON-serializable). */
  tagsSorter?: "alpha";
  /**
   * Note: function callbacks cannot be passed via Nitro configuration (not JSON-serializable).
   */
  onComplete?: never;
  layout?: string;
  configUrl?: string;
  oauth2RedirectUrl?: string;
  withCredentials?: boolean;
  [key: string]: unknown;
}

/**
 * Nitro OpenAPI configuration.
 *
 * @see https://nitro.build/config#openapi
 * @see https://nitro.build/docs/openapi
 */
export interface NitroOpenAPIConfig {
  /**
   * OpenAPI document metadata.
   */
  meta?: {
    title?: string;
    description?: string;
    version?: string;
  };

  /**
   * Route for the OpenAPI JSON endpoint.
   *
   * @default "/_openapi.json"
   */
  route?: string;

  /**
   * Enable OpenAPI generation for production builds.
   *
   * - `"runtime"` — generate at runtime (allows middleware usage).
   * - `"prerender"` — prerender the JSON response at build time (most efficient).
   * - `false` — disable in production.
   *
   * @see https://nitro.build/config#openapi
   */
  production?: false | "runtime" | "prerender";

  /**
   * UI configurations for interactive API documentation.
   */
  ui?: {
    /**
     * Scalar UI configuration.
     *
     * Set to `false` to disable.
     */
    scalar?:
      | false
      | (Partial<unknown> & {
          /**
           * Route for Scalar UI.
           *
           * @default "/_scalar"
           */
          route?: string;
        });
    /**
     * Swagger UI configuration.
     *
     * Set to `false` to disable.
     *
     * @see https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
     */
    swagger?:
      | false
      | (SwaggerUIConfig & {
          /**
           * Route for Swagger UI.
           *
           * @default "/_swagger"
           */
          route?: string;
        });
  };
}