@celljs/openapi 0.0.0-stage → 4.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +85 -2
- package/cell.schema.json +41 -0
- package/cell.yml +12 -0
- package/esm/common/annotation.d.ts +60 -0
- package/esm/common/annotation.js +73 -0
- package/esm/common/annotation.js.map +1 -0
- package/esm/common/constants.d.ts +11 -0
- package/esm/common/constants.js +12 -0
- package/esm/common/constants.js.map +1 -0
- package/esm/common/index.d.ts +3 -0
- package/esm/common/index.js +4 -0
- package/esm/common/index.js.map +1 -0
- package/esm/common/openapi-protocol.d.ts +143 -0
- package/esm/common/openapi-protocol.js +2 -0
- package/esm/common/openapi-protocol.js.map +1 -0
- package/esm/node/index.d.ts +6 -0
- package/esm/node/index.js +7 -0
- package/esm/node/index.js.map +1 -0
- package/esm/node/module.d.ts +3 -0
- package/esm/node/module.js +4 -0
- package/esm/node/module.js.map +1 -0
- package/esm/node/openapi-document-provider.d.ts +39 -0
- package/esm/node/openapi-document-provider.js +310 -0
- package/esm/node/openapi-document-provider.js.map +1 -0
- package/esm/node/openapi-middleware.d.ts +17 -0
- package/esm/node/openapi-middleware.js +76 -0
- package/esm/node/openapi-middleware.js.map +1 -0
- package/esm/node/openapi-node-protocol.d.ts +7 -0
- package/esm/node/openapi-node-protocol.js +4 -0
- package/esm/node/openapi-node-protocol.js.map +1 -0
- package/esm/node/openapi-path-util.d.ts +10 -0
- package/esm/node/openapi-path-util.js +84 -0
- package/esm/node/openapi-path-util.js.map +1 -0
- package/esm/node/schema-builder.d.ts +39 -0
- package/esm/node/schema-builder.js +271 -0
- package/esm/node/schema-builder.js.map +1 -0
- package/esm/node/swagger-ui.d.ts +10 -0
- package/esm/node/swagger-ui.js +31 -0
- package/esm/node/swagger-ui.js.map +1 -0
- package/esm/package.json +3 -0
- package/lib/common/annotation.d.ts +61 -0
- package/lib/common/annotation.d.ts.map +1 -0
- package/lib/common/annotation.js +86 -0
- package/lib/common/annotation.js.map +1 -0
- package/lib/common/constants.d.ts +12 -0
- package/lib/common/constants.d.ts.map +1 -0
- package/lib/common/constants.js +15 -0
- package/lib/common/constants.js.map +1 -0
- package/lib/common/index.d.ts +4 -0
- package/lib/common/index.d.ts.map +1 -0
- package/lib/common/index.js +20 -0
- package/lib/common/index.js.map +1 -0
- package/lib/common/openapi-protocol.d.ts +144 -0
- package/lib/common/openapi-protocol.d.ts.map +1 -0
- package/lib/common/openapi-protocol.js +3 -0
- package/lib/common/openapi-protocol.js.map +1 -0
- package/lib/node/index.d.ts +7 -0
- package/lib/node/index.d.ts.map +1 -0
- package/lib/node/index.js +23 -0
- package/lib/node/index.js.map +1 -0
- package/lib/node/module.d.ts +4 -0
- package/lib/node/module.d.ts.map +1 -0
- package/lib/node/module.js +6 -0
- package/lib/node/module.js.map +1 -0
- package/lib/node/openapi-document-provider.d.ts +40 -0
- package/lib/node/openapi-document-provider.d.ts.map +1 -0
- package/lib/node/openapi-document-provider.js +313 -0
- package/lib/node/openapi-document-provider.js.map +1 -0
- package/lib/node/openapi-middleware.d.ts +18 -0
- package/lib/node/openapi-middleware.d.ts.map +1 -0
- package/lib/node/openapi-middleware.js +79 -0
- package/lib/node/openapi-middleware.js.map +1 -0
- package/lib/node/openapi-node-protocol.d.ts +8 -0
- package/lib/node/openapi-node-protocol.d.ts.map +1 -0
- package/lib/node/openapi-node-protocol.js +7 -0
- package/lib/node/openapi-node-protocol.js.map +1 -0
- package/lib/node/openapi-path-util.d.ts +11 -0
- package/lib/node/openapi-path-util.d.ts.map +1 -0
- package/lib/node/openapi-path-util.js +87 -0
- package/lib/node/openapi-path-util.js.map +1 -0
- package/lib/node/openapi.spec.d.ts +30 -0
- package/lib/node/openapi.spec.d.ts.map +1 -0
- package/lib/node/openapi.spec.js +268 -0
- package/lib/node/openapi.spec.js.map +1 -0
- package/lib/node/schema-builder.d.ts +40 -0
- package/lib/node/schema-builder.d.ts.map +1 -0
- package/lib/node/schema-builder.js +275 -0
- package/lib/node/schema-builder.js.map +1 -0
- package/lib/node/schema-builder.spec.d.ts +2 -0
- package/lib/node/schema-builder.spec.d.ts.map +1 -0
- package/lib/node/schema-builder.spec.js +143 -0
- package/lib/node/schema-builder.spec.js.map +1 -0
- package/lib/node/swagger-ui.d.ts +11 -0
- package/lib/node/swagger-ui.d.ts.map +1 -0
- package/lib/node/swagger-ui.js +34 -0
- package/lib/node/swagger-ui.js.map +1 -0
- package/lib/package.spec.d.ts +2 -0
- package/lib/package.spec.d.ts.map +1 -0
- package/lib/package.spec.js +7 -0
- package/lib/package.spec.js.map +1 -0
- package/package.json +78 -4
- package/src/common/annotation.ts +130 -0
- package/src/common/constants.ts +12 -0
- package/src/common/index.ts +3 -0
- package/src/common/openapi-protocol.ts +154 -0
- package/src/node/index.ts +6 -0
- package/src/node/module.ts +4 -0
- package/src/node/openapi-document-provider.ts +334 -0
- package/src/node/openapi-middleware.ts +59 -0
- package/src/node/openapi-node-protocol.ts +11 -0
- package/src/node/openapi-path-util.ts +75 -0
- package/src/node/openapi.spec.ts +219 -0
- package/src/node/schema-builder.spec.ts +124 -0
- package/src/node/schema-builder.ts +282 -0
- package/src/node/swagger-ui.ts +38 -0
- package/src/package.spec.ts +5 -0
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
import { DEFAULT_BEARER_SCHEME, OPENAPI_METADATA_KEY } from './constants';
|
|
2
|
+
import type { ParameterLocation, SchemaObject, SecurityRequirementObject, TypeRef } from './openapi-protocol';
|
|
3
|
+
|
|
4
|
+
export interface ApiOperationOptions {
|
|
5
|
+
summary?: string;
|
|
6
|
+
description?: string;
|
|
7
|
+
/** Default: `<ControllerClass>_<method>`. */
|
|
8
|
+
operationId?: string;
|
|
9
|
+
deprecated?: boolean;
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
export interface ApiResponseOptions {
|
|
13
|
+
/** Default: 200. */
|
|
14
|
+
status?: number | 'default';
|
|
15
|
+
description?: string;
|
|
16
|
+
/** Type of the body; `[User]` for a list. */
|
|
17
|
+
type?: TypeRef;
|
|
18
|
+
/** A schema written by hand; wins over `type`. */
|
|
19
|
+
schema?: SchemaObject;
|
|
20
|
+
/** Default: by the view of the method (`application/json`, `text/plain` for `@Text()`...). */
|
|
21
|
+
contentType?: string;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
export type ApiPropertyOptions = Omit<SchemaObject, 'type' | 'required' | 'enum' | 'items'> & {
|
|
25
|
+
/** Default: the TypeScript type of the property (`design:type`); needed for arrays (`[Item]`). */
|
|
26
|
+
type?: TypeRef;
|
|
27
|
+
/** Default: true. */
|
|
28
|
+
required?: boolean;
|
|
29
|
+
/** Values, or a TypeScript enum. */
|
|
30
|
+
enum?: any[] | Record<string, any>;
|
|
31
|
+
items?: SchemaObject;
|
|
32
|
+
};
|
|
33
|
+
|
|
34
|
+
export type ApiParameterOptions = Omit<ApiPropertyOptions, 'description' | 'example' | 'deprecated'> & {
|
|
35
|
+
name: string;
|
|
36
|
+
description?: string;
|
|
37
|
+
example?: any;
|
|
38
|
+
deprecated?: boolean;
|
|
39
|
+
};
|
|
40
|
+
|
|
41
|
+
export interface ApiParameterMetadata extends ApiParameterOptions {
|
|
42
|
+
in: ParameterLocation;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
export interface ApiPropertyMetadata {
|
|
46
|
+
key: string;
|
|
47
|
+
options: ApiPropertyOptions;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
function defineList(key: string, value: any, target: any, propertyKey?: string | symbol): void {
|
|
51
|
+
const list: any[] = (propertyKey === undefined ? Reflect.getOwnMetadata(key, target) : Reflect.getOwnMetadata(key, target, propertyKey)) || [];
|
|
52
|
+
list.push(value);
|
|
53
|
+
if (propertyKey === undefined) {
|
|
54
|
+
Reflect.defineMetadata(key, list, target);
|
|
55
|
+
} else {
|
|
56
|
+
Reflect.defineMetadata(key, list, target, propertyKey);
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** A decorator for a controller (`target` is the class) or one of its methods (metadata goes on the class with the method name). */
|
|
61
|
+
function classOrMethod(key: string, value: any, list: boolean): ClassDecorator & MethodDecorator {
|
|
62
|
+
return ((target: any, propertyKey?: string | symbol) => {
|
|
63
|
+
const owner = propertyKey === undefined ? target : target.constructor;
|
|
64
|
+
if (list) {
|
|
65
|
+
defineList(key, value, owner, propertyKey);
|
|
66
|
+
} else if (propertyKey === undefined) {
|
|
67
|
+
Reflect.defineMetadata(key, value, owner);
|
|
68
|
+
} else {
|
|
69
|
+
Reflect.defineMetadata(key, value, owner, propertyKey);
|
|
70
|
+
}
|
|
71
|
+
}) as ClassDecorator & MethodDecorator;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/** Groups the operations of a controller or a method in the UI. Default: the controller name without `Controller`. */
|
|
75
|
+
export function ApiTags(...tags: string[]): ClassDecorator & MethodDecorator {
|
|
76
|
+
return classOrMethod(OPENAPI_METADATA_KEY.tags, tags, false);
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
export function ApiOperation(options: ApiOperationOptions): MethodDecorator {
|
|
80
|
+
return classOrMethod(OPENAPI_METADATA_KEY.operation, options, false);
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/** A possible response; on a controller it applies to all its methods. Repeat it for several statuses. */
|
|
84
|
+
export function ApiResponse(options: ApiResponseOptions): ClassDecorator & MethodDecorator {
|
|
85
|
+
return classOrMethod(OPENAPI_METADATA_KEY.responses, options, true);
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/** Describes a property of a request or response class. Properties with class-validator decorators are found without it. */
|
|
89
|
+
export function ApiProperty(options: ApiPropertyOptions = {}): PropertyDecorator {
|
|
90
|
+
return (target: any, propertyKey: string | symbol) => {
|
|
91
|
+
defineList(OPENAPI_METADATA_KEY.properties, { key: propertyKey.toString(), options } as ApiPropertyMetadata, target.constructor);
|
|
92
|
+
};
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
export function ApiPropertyOptional(options: ApiPropertyOptions = {}): PropertyDecorator {
|
|
96
|
+
return ApiProperty({ ...options, required: false });
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
function parameter(location: ParameterLocation, options: ApiParameterOptions): MethodDecorator {
|
|
100
|
+
return classOrMethod(OPENAPI_METADATA_KEY.parameters, { ...options, in: location } as ApiParameterMetadata, true);
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/** Describes a path parameter; it is found from the route without it. */
|
|
104
|
+
export function ApiParam(options: ApiParameterOptions): MethodDecorator {
|
|
105
|
+
return parameter('path', options);
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/** Describes a query parameter, or documents one the method reads from the request itself. */
|
|
109
|
+
export function ApiQuery(options: ApiParameterOptions): MethodDecorator {
|
|
110
|
+
return parameter('query', options);
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
export function ApiHeader(options: ApiParameterOptions): MethodDecorator {
|
|
114
|
+
return parameter('header', options);
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/** Requires the security scheme `name` (declared in `openapi.document.components.securitySchemes`). */
|
|
118
|
+
export function ApiSecurity(name: string, scopes: string[] = []): ClassDecorator & MethodDecorator {
|
|
119
|
+
return classOrMethod(OPENAPI_METADATA_KEY.security, { [name]: scopes } as SecurityRequirementObject, true);
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/** Requires a bearer token (`Authorization: Bearer ...`); the scheme `bearer` is declared when it is missing. */
|
|
123
|
+
export function ApiBearerAuth(name = DEFAULT_BEARER_SCHEME): ClassDecorator & MethodDecorator {
|
|
124
|
+
return ApiSecurity(name);
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/** Leaves a controller or a method out of the document. */
|
|
128
|
+
export function ApiExclude(): ClassDecorator & MethodDecorator {
|
|
129
|
+
return classOrMethod(OPENAPI_METADATA_KEY.exclude, true, false);
|
|
130
|
+
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
export const OPENAPI_METADATA_KEY = {
|
|
2
|
+
tags: 'cell:openapi:tags',
|
|
3
|
+
operation: 'cell:openapi:operation',
|
|
4
|
+
responses: 'cell:openapi:responses',
|
|
5
|
+
parameters: 'cell:openapi:parameters',
|
|
6
|
+
properties: 'cell:openapi:properties',
|
|
7
|
+
security: 'cell:openapi:security',
|
|
8
|
+
exclude: 'cell:openapi:exclude',
|
|
9
|
+
};
|
|
10
|
+
|
|
11
|
+
/** Name of the security scheme that `@ApiBearerAuth()` refers to when none is given. */
|
|
12
|
+
export const DEFAULT_BEARER_SCHEME = 'bearer';
|
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The parts of an OpenAPI 3.0 document that Cell generates. Fields Cell does not know are kept as they are,
|
|
3
|
+
* so a document can carry any extension from `openapi.document`.
|
|
4
|
+
*/
|
|
5
|
+
export interface OpenApiDocument {
|
|
6
|
+
openapi: string;
|
|
7
|
+
info: InfoObject;
|
|
8
|
+
servers?: ServerObject[];
|
|
9
|
+
paths: Record<string, PathItemObject>;
|
|
10
|
+
components?: ComponentsObject;
|
|
11
|
+
security?: SecurityRequirementObject[];
|
|
12
|
+
tags?: TagObject[];
|
|
13
|
+
externalDocs?: { url: string; description?: string };
|
|
14
|
+
[extension: string]: any;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
export interface InfoObject {
|
|
18
|
+
title: string;
|
|
19
|
+
version: string;
|
|
20
|
+
description?: string;
|
|
21
|
+
[extension: string]: any;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
export interface ServerObject {
|
|
25
|
+
url: string;
|
|
26
|
+
description?: string;
|
|
27
|
+
[extension: string]: any;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
export interface TagObject {
|
|
31
|
+
name: string;
|
|
32
|
+
description?: string;
|
|
33
|
+
[extension: string]: any;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
export type PathItemObject = Record<string, OperationObject>;
|
|
37
|
+
|
|
38
|
+
export interface OperationObject {
|
|
39
|
+
tags?: string[];
|
|
40
|
+
summary?: string;
|
|
41
|
+
description?: string;
|
|
42
|
+
operationId?: string;
|
|
43
|
+
parameters?: ParameterObject[];
|
|
44
|
+
requestBody?: RequestBodyObject;
|
|
45
|
+
responses: Record<string, ResponseObject>;
|
|
46
|
+
deprecated?: boolean;
|
|
47
|
+
security?: SecurityRequirementObject[];
|
|
48
|
+
[extension: string]: any;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
export type ParameterLocation = 'path' | 'query' | 'header' | 'cookie';
|
|
52
|
+
|
|
53
|
+
export interface ParameterObject {
|
|
54
|
+
name: string;
|
|
55
|
+
in: ParameterLocation;
|
|
56
|
+
description?: string;
|
|
57
|
+
required?: boolean;
|
|
58
|
+
deprecated?: boolean;
|
|
59
|
+
schema?: SchemaObject;
|
|
60
|
+
example?: any;
|
|
61
|
+
[extension: string]: any;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
export interface RequestBodyObject {
|
|
65
|
+
description?: string;
|
|
66
|
+
required?: boolean;
|
|
67
|
+
content: Record<string, MediaTypeObject>;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
export interface MediaTypeObject {
|
|
71
|
+
schema?: SchemaObject;
|
|
72
|
+
example?: any;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
export interface ResponseObject {
|
|
76
|
+
description: string;
|
|
77
|
+
content?: Record<string, MediaTypeObject>;
|
|
78
|
+
headers?: Record<string, { description?: string; schema?: SchemaObject }>;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
export interface SchemaObject {
|
|
82
|
+
$ref?: string;
|
|
83
|
+
type?: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object';
|
|
84
|
+
format?: string;
|
|
85
|
+
items?: SchemaObject;
|
|
86
|
+
properties?: Record<string, SchemaObject>;
|
|
87
|
+
required?: string[];
|
|
88
|
+
additionalProperties?: boolean | SchemaObject;
|
|
89
|
+
enum?: any[];
|
|
90
|
+
description?: string;
|
|
91
|
+
example?: any;
|
|
92
|
+
default?: any;
|
|
93
|
+
nullable?: boolean;
|
|
94
|
+
deprecated?: boolean;
|
|
95
|
+
readOnly?: boolean;
|
|
96
|
+
writeOnly?: boolean;
|
|
97
|
+
minimum?: number;
|
|
98
|
+
maximum?: number;
|
|
99
|
+
exclusiveMinimum?: boolean;
|
|
100
|
+
exclusiveMaximum?: boolean;
|
|
101
|
+
minLength?: number;
|
|
102
|
+
maxLength?: number;
|
|
103
|
+
pattern?: string;
|
|
104
|
+
minItems?: number;
|
|
105
|
+
maxItems?: number;
|
|
106
|
+
oneOf?: SchemaObject[];
|
|
107
|
+
allOf?: SchemaObject[];
|
|
108
|
+
anyOf?: SchemaObject[];
|
|
109
|
+
[extension: string]: any;
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
export interface ComponentsObject {
|
|
113
|
+
schemas?: Record<string, SchemaObject>;
|
|
114
|
+
securitySchemes?: Record<string, SecuritySchemeObject>;
|
|
115
|
+
[extension: string]: any;
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
export interface SecuritySchemeObject {
|
|
119
|
+
type: 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';
|
|
120
|
+
description?: string;
|
|
121
|
+
name?: string;
|
|
122
|
+
in?: 'query' | 'header' | 'cookie';
|
|
123
|
+
scheme?: string;
|
|
124
|
+
bearerFormat?: string;
|
|
125
|
+
[extension: string]: any;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
export type SecurityRequirementObject = Record<string, string[]>;
|
|
129
|
+
|
|
130
|
+
/**
|
|
131
|
+
* What describes the type of a property, a parameter, a body or a response:
|
|
132
|
+
* a class (`User`, `String`, `Number`, `Boolean`, `Date`), an array of one (`[User]`) or an OpenAPI type name (`'integer'`).
|
|
133
|
+
*/
|
|
134
|
+
export type TypeRef = Constructor | [Constructor] | [string] | NonNullable<SchemaObject['type']>;
|
|
135
|
+
|
|
136
|
+
/** A class, including the built-in ones (`String`, `Date`...) and abstract classes. */
|
|
137
|
+
export type Constructor = abstract new (...args: any[]) => any;
|
|
138
|
+
|
|
139
|
+
/** `openapi` in cell.yml (backend). */
|
|
140
|
+
export interface OpenApiOptions {
|
|
141
|
+
/** false: neither the document nor the UI is served. */
|
|
142
|
+
enabled: boolean;
|
|
143
|
+
/** Path of the JSON document, under `server.path`. */
|
|
144
|
+
url: string;
|
|
145
|
+
ui: {
|
|
146
|
+
enabled: boolean;
|
|
147
|
+
/** Path of the Swagger UI page, under `server.path`. */
|
|
148
|
+
url: string;
|
|
149
|
+
/** Where the page loads swagger-ui-dist from (swagger-ui.css, swagger-ui-bundle.js). */
|
|
150
|
+
cdn: string;
|
|
151
|
+
};
|
|
152
|
+
/** Merged into the generated document: info, servers, tags, components.securitySchemes, security... */
|
|
153
|
+
document: Partial<OpenApiDocument>;
|
|
154
|
+
}
|
|
@@ -0,0 +1,334 @@
|
|
|
1
|
+
import { Autowired, Component, Value } from '@celljs/core';
|
|
2
|
+
import { type CatchMetadata, type MethodMetadata, type PathRouteMetadata, type Route, RouteProvider } from '@celljs/mvc/lib/node';
|
|
3
|
+
import {
|
|
4
|
+
type ApiOperationOptions,
|
|
5
|
+
type ApiParameterMetadata,
|
|
6
|
+
type ApiResponseOptions,
|
|
7
|
+
type Constructor,
|
|
8
|
+
DEFAULT_BEARER_SCHEME,
|
|
9
|
+
OPENAPI_METADATA_KEY,
|
|
10
|
+
type OpenApiDocument,
|
|
11
|
+
type OpenApiOptions,
|
|
12
|
+
type OperationObject,
|
|
13
|
+
type ParameterLocation,
|
|
14
|
+
type ParameterObject,
|
|
15
|
+
type PathItemObject,
|
|
16
|
+
type RequestBodyObject,
|
|
17
|
+
type ResponseObject,
|
|
18
|
+
type SchemaObject,
|
|
19
|
+
type SecurityRequirementObject,
|
|
20
|
+
} from '../common';
|
|
21
|
+
import { OpenApiDocumentProvider } from './openapi-node-protocol';
|
|
22
|
+
import { OpenApiPathUtil } from './openapi-path-util';
|
|
23
|
+
import { SchemaBuilder, SchemaUtil } from './schema-builder';
|
|
24
|
+
|
|
25
|
+
const METHOD_ORDER = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace'];
|
|
26
|
+
|
|
27
|
+
const STATUS_DESCRIPTIONS: Record<string, string> = {
|
|
28
|
+
200: 'OK',
|
|
29
|
+
201: 'Created',
|
|
30
|
+
202: 'Accepted',
|
|
31
|
+
204: 'No Content',
|
|
32
|
+
301: 'Moved Permanently',
|
|
33
|
+
302: 'Found',
|
|
34
|
+
304: 'Not Modified',
|
|
35
|
+
400: 'Bad Request',
|
|
36
|
+
401: 'Unauthorized',
|
|
37
|
+
403: 'Forbidden',
|
|
38
|
+
404: 'Not Found',
|
|
39
|
+
409: 'Conflict',
|
|
40
|
+
422: 'Unprocessable Entity',
|
|
41
|
+
429: 'Too Many Requests',
|
|
42
|
+
500: 'Internal Server Error',
|
|
43
|
+
default: 'Unexpected error',
|
|
44
|
+
};
|
|
45
|
+
|
|
46
|
+
const VIEW_CONTENT_TYPES: Record<string, string> = {
|
|
47
|
+
json: 'application/json',
|
|
48
|
+
text: 'text/plain',
|
|
49
|
+
html: 'text/html',
|
|
50
|
+
file: 'application/octet-stream',
|
|
51
|
+
};
|
|
52
|
+
|
|
53
|
+
/** Types that are not classes of the application. */
|
|
54
|
+
const BUILT_IN_TYPES: unknown[] = [String, Number, Boolean, Date, Object, Array, Promise, Function, Symbol];
|
|
55
|
+
|
|
56
|
+
/** What one route of a controller method contributes, before it is placed under its paths. */
|
|
57
|
+
interface RouteOperation {
|
|
58
|
+
method: string;
|
|
59
|
+
pattern: string;
|
|
60
|
+
operation: OperationObject;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Builds the OpenAPI document from the routes of `@celljs/mvc` (the same metadata that serves the requests)
|
|
65
|
+
* and the `@Api*` decorators; `openapi.document` is merged over it.
|
|
66
|
+
*/
|
|
67
|
+
@Component(OpenApiDocumentProvider)
|
|
68
|
+
export class OpenApiDocumentProviderImpl implements OpenApiDocumentProvider {
|
|
69
|
+
@Autowired(RouteProvider)
|
|
70
|
+
protected readonly routeProvider: RouteProvider;
|
|
71
|
+
|
|
72
|
+
@Value('openapi')
|
|
73
|
+
protected readonly options: OpenApiOptions;
|
|
74
|
+
|
|
75
|
+
@Value('mvc.defaultViewName')
|
|
76
|
+
protected readonly defaultViewName: string;
|
|
77
|
+
|
|
78
|
+
protected document?: Promise<OpenApiDocument>;
|
|
79
|
+
|
|
80
|
+
provide(): Promise<OpenApiDocument> {
|
|
81
|
+
if (!this.document) {
|
|
82
|
+
this.document = this.routeProvider.provide().then(route => this.build(route));
|
|
83
|
+
}
|
|
84
|
+
return this.document;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
protected build(route: Route): OpenApiDocument {
|
|
88
|
+
const base = this.options?.document || {};
|
|
89
|
+
const schemas = new SchemaBuilder();
|
|
90
|
+
const routes: RouteOperation[] = [];
|
|
91
|
+
for (const [method, metadatas] of route.mapping) {
|
|
92
|
+
for (const metadata of metadatas) {
|
|
93
|
+
if (typeof metadata.path === 'string' && !this.isExcluded(metadata)) {
|
|
94
|
+
routes.push({ method: method.toLowerCase(), pattern: metadata.path, operation: this.buildOperation(metadata, schemas) });
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
const paths = this.buildPaths(routes);
|
|
99
|
+
const securitySchemes = { ...base.components?.securitySchemes };
|
|
100
|
+
if (this.usesScheme(paths, DEFAULT_BEARER_SCHEME) && !securitySchemes[DEFAULT_BEARER_SCHEME]) {
|
|
101
|
+
securitySchemes[DEFAULT_BEARER_SCHEME] = { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' };
|
|
102
|
+
}
|
|
103
|
+
const components = { ...base.components, schemas: { ...schemas.schemas, ...base.components?.schemas }, securitySchemes };
|
|
104
|
+
for (const key of ['schemas', 'securitySchemes'] as const) {
|
|
105
|
+
if (!Object.keys(components[key]).length) {
|
|
106
|
+
delete components[key];
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
const document: OpenApiDocument = {
|
|
110
|
+
...base,
|
|
111
|
+
openapi: base.openapi || '3.0.3',
|
|
112
|
+
info: { title: 'API', version: '1.0.0', ...base.info },
|
|
113
|
+
paths: { ...paths, ...base.paths },
|
|
114
|
+
};
|
|
115
|
+
if (Object.keys(components).length) {
|
|
116
|
+
document.components = components;
|
|
117
|
+
}
|
|
118
|
+
return document;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/** Places the operations under their OpenAPI paths, sorted by path then by method; operation ids stay unique. */
|
|
122
|
+
protected buildPaths(routes: RouteOperation[]): Record<string, PathItemObject> {
|
|
123
|
+
const items: Record<string, PathItemObject> = {};
|
|
124
|
+
const operationIds = new Set<string>();
|
|
125
|
+
for (const { method, pattern, operation } of routes) {
|
|
126
|
+
for (const expanded of OpenApiPathUtil.expand(pattern)) {
|
|
127
|
+
const { path, names } = OpenApiPathUtil.convert(expanded);
|
|
128
|
+
items[path] = items[path] || {};
|
|
129
|
+
const item = items[path];
|
|
130
|
+
if (item[method]) {
|
|
131
|
+
continue;
|
|
132
|
+
}
|
|
133
|
+
item[method] = this.withPathParameters({ ...operation }, names, operationIds);
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
const sorted: Record<string, PathItemObject> = {};
|
|
137
|
+
for (const path of Object.keys(items).sort()) {
|
|
138
|
+
sorted[path] = {};
|
|
139
|
+
for (const method of Object.keys(items[path]).sort((a, b) => METHOD_ORDER.indexOf(a) - METHOD_ORDER.indexOf(b))) {
|
|
140
|
+
sorted[path][method] = items[path][method];
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
return sorted;
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/** Keeps the path parameters of this path (optional parts differ), adds the undeclared ones as strings. */
|
|
147
|
+
protected withPathParameters(operation: OperationObject, names: string[], operationIds: Set<string>): OperationObject {
|
|
148
|
+
const declared = operation.parameters || [];
|
|
149
|
+
const parameters = declared.filter(p => p.in !== 'path' || names.includes(p.name));
|
|
150
|
+
for (const name of names) {
|
|
151
|
+
if (!parameters.some(p => p.in === 'path' && p.name === name)) {
|
|
152
|
+
parameters.push({ name, in: 'path', required: true, schema: { type: 'string' } });
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
parameters.sort((a, b) => Number(b.in === 'path') - Number(a.in === 'path'));
|
|
156
|
+
if (parameters.length) {
|
|
157
|
+
operation.parameters = parameters;
|
|
158
|
+
} else {
|
|
159
|
+
delete operation.parameters;
|
|
160
|
+
}
|
|
161
|
+
if (operation.operationId) {
|
|
162
|
+
let id = operation.operationId;
|
|
163
|
+
for (let i = 2; operationIds.has(id); i++) {
|
|
164
|
+
id = `${operation.operationId}_${i}`;
|
|
165
|
+
}
|
|
166
|
+
operationIds.add(id);
|
|
167
|
+
operation.operationId = id;
|
|
168
|
+
}
|
|
169
|
+
return operation;
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
protected buildOperation(metadata: PathRouteMetadata, schemas: SchemaBuilder): OperationObject {
|
|
173
|
+
const target = metadata.controllerMetadata.target;
|
|
174
|
+
const key = (metadata.methodMetadata as MethodMetadata | CatchMetadata).key;
|
|
175
|
+
const options: ApiOperationOptions = this.getMetadata(OPENAPI_METADATA_KEY.operation, target, key) || {};
|
|
176
|
+
const tags: string[] = this.getMetadata(OPENAPI_METADATA_KEY.tags, target, key) ||
|
|
177
|
+
this.getMetadata(OPENAPI_METADATA_KEY.tags, target) || [target.name.replace(/Controller$/, '') || target.name];
|
|
178
|
+
const operation: OperationObject = {
|
|
179
|
+
tags,
|
|
180
|
+
summary: options.summary,
|
|
181
|
+
description: options.description,
|
|
182
|
+
operationId: options.operationId || `${target.name}_${key.toString()}`,
|
|
183
|
+
parameters: this.buildParameters(metadata, schemas),
|
|
184
|
+
requestBody: this.buildRequestBody(metadata, schemas),
|
|
185
|
+
responses: this.buildResponses(metadata, schemas),
|
|
186
|
+
deprecated: options.deprecated,
|
|
187
|
+
security: this.getMetadata(OPENAPI_METADATA_KEY.security, target, key) || this.getMetadata(OPENAPI_METADATA_KEY.security, target),
|
|
188
|
+
};
|
|
189
|
+
for (const name of Object.keys(operation)) {
|
|
190
|
+
if (operation[name] === undefined) {
|
|
191
|
+
delete operation[name];
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
return operation;
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
protected buildParameters(metadata: PathRouteMetadata, schemas: SchemaBuilder): ParameterObject[] {
|
|
198
|
+
const types = this.parameterTypes(metadata);
|
|
199
|
+
const parameters: ParameterObject[] = [];
|
|
200
|
+
const add = (location: ParameterLocation, list: { name?: string; parameterIndex: number }[] = []) => {
|
|
201
|
+
for (const { name, parameterIndex } of list) {
|
|
202
|
+
const type = types[parameterIndex];
|
|
203
|
+
if (name) {
|
|
204
|
+
parameters.push({ name, in: location, required: location === 'path' || undefined, schema: this.scalarSchema(schemas.resolve(type)) });
|
|
205
|
+
} else if (location === 'query' && this.isClass(type)) {
|
|
206
|
+
// `@Query() filter: Filter`: the properties of the class are the query parameters.
|
|
207
|
+
const schema = schemas.build(type);
|
|
208
|
+
for (const [property, propertySchema] of Object.entries(schema.properties || {})) {
|
|
209
|
+
const { description, example, deprecated, ...rest } = propertySchema;
|
|
210
|
+
const required = schema.required?.includes(property) || undefined;
|
|
211
|
+
parameters.push({ name: property, in: 'query', description, required, deprecated, example, schema: rest });
|
|
212
|
+
}
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
};
|
|
216
|
+
add('path', metadata.paramMetadata);
|
|
217
|
+
add('query', metadata.queryMetadata);
|
|
218
|
+
add('header', metadata.requestHeaderMetadata);
|
|
219
|
+
add('cookie', metadata.requestCookieMetadata);
|
|
220
|
+
const explicit: ApiParameterMetadata[] =
|
|
221
|
+
this.getMetadata(OPENAPI_METADATA_KEY.parameters, metadata.controllerMetadata.target, this.methodKey(metadata)) || [];
|
|
222
|
+
for (const { name, in: location, description, example, deprecated, ...schemaOptions } of explicit) {
|
|
223
|
+
const index = parameters.findIndex(p => p.name === name && p.in === location);
|
|
224
|
+
const found = index === -1 ? ({ name, in: location, schema: { type: 'string' } } as ParameterObject) : parameters[index];
|
|
225
|
+
const { required } = schemaOptions;
|
|
226
|
+
const parameter: ParameterObject = {
|
|
227
|
+
...found,
|
|
228
|
+
description: description ?? found.description,
|
|
229
|
+
required: location === 'path' ? true : (required ?? found.required),
|
|
230
|
+
deprecated: deprecated ?? found.deprecated,
|
|
231
|
+
example: example ?? found.example,
|
|
232
|
+
schema: SchemaUtil.normalize(schemas.fromOptions(schemaOptions, found.schema)),
|
|
233
|
+
};
|
|
234
|
+
if (index === -1) {
|
|
235
|
+
parameters.push(parameter);
|
|
236
|
+
} else {
|
|
237
|
+
parameters[index] = parameter;
|
|
238
|
+
}
|
|
239
|
+
}
|
|
240
|
+
for (const parameter of parameters) {
|
|
241
|
+
for (const field of ['description', 'required', 'deprecated', 'example'] as const) {
|
|
242
|
+
if (parameter[field] === undefined) {
|
|
243
|
+
delete parameter[field];
|
|
244
|
+
}
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
return parameters;
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
protected buildRequestBody(metadata: PathRouteMetadata, schemas: SchemaBuilder): RequestBodyObject | undefined {
|
|
251
|
+
const bodies = metadata.bodyMetadata || [];
|
|
252
|
+
if (!bodies.length) {
|
|
253
|
+
return undefined;
|
|
254
|
+
}
|
|
255
|
+
const types = this.parameterTypes(metadata);
|
|
256
|
+
const whole = bodies.find(body => !body.name);
|
|
257
|
+
let schema: SchemaObject;
|
|
258
|
+
if (whole) {
|
|
259
|
+
schema = schemas.resolve(types[whole.parameterIndex]) || { type: 'object' };
|
|
260
|
+
} else {
|
|
261
|
+
const properties: Record<string, SchemaObject> = {};
|
|
262
|
+
for (const { name, parameterIndex } of bodies) {
|
|
263
|
+
properties[name as string] = schemas.resolve(types[parameterIndex]) || {};
|
|
264
|
+
}
|
|
265
|
+
schema = { type: 'object', properties, required: Object.keys(properties) };
|
|
266
|
+
}
|
|
267
|
+
return { required: true, content: { 'application/json': { schema } } };
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
protected buildResponses(metadata: PathRouteMetadata, schemas: SchemaBuilder): Record<string, ResponseObject> {
|
|
271
|
+
const target = metadata.controllerMetadata.target;
|
|
272
|
+
const key = this.methodKey(metadata);
|
|
273
|
+
const contentType = VIEW_CONTENT_TYPES[metadata.viewMetadata?.viewName || this.defaultViewName] || VIEW_CONTENT_TYPES.json;
|
|
274
|
+
const declared: ApiResponseOptions[] = [
|
|
275
|
+
...(this.getMetadata(OPENAPI_METADATA_KEY.responses, target) || []),
|
|
276
|
+
...(this.getMetadata(OPENAPI_METADATA_KEY.responses, target, key) || []),
|
|
277
|
+
];
|
|
278
|
+
const responses: Record<string, ResponseObject> = {};
|
|
279
|
+
for (const options of declared) {
|
|
280
|
+
const status = String(options.status ?? 200);
|
|
281
|
+
const response: ResponseObject = { description: options.description || STATUS_DESCRIPTIONS[status] || 'Response' };
|
|
282
|
+
const schema = options.schema || schemas.resolve(options.type);
|
|
283
|
+
if (schema) {
|
|
284
|
+
response.content = { [options.contentType || contentType]: { schema } };
|
|
285
|
+
}
|
|
286
|
+
responses[status] = response;
|
|
287
|
+
}
|
|
288
|
+
if (!Object.keys(responses).some(status => status.startsWith('2'))) {
|
|
289
|
+
const returnType = Reflect.getMetadata('design:returntype', target.prototype, key);
|
|
290
|
+
const response: ResponseObject = { description: 'OK' };
|
|
291
|
+
if (returnType !== undefined) {
|
|
292
|
+
const schema = contentType === VIEW_CONTENT_TYPES.text ? { type: 'string' as const } : schemas.resolve(returnType);
|
|
293
|
+
response.content = { [contentType]: schema ? { schema } : {} };
|
|
294
|
+
}
|
|
295
|
+
responses['200'] = response;
|
|
296
|
+
}
|
|
297
|
+
return Object.fromEntries(Object.entries(responses).sort(([a], [b]) => a.localeCompare(b)));
|
|
298
|
+
}
|
|
299
|
+
|
|
300
|
+
protected isExcluded(metadata: PathRouteMetadata): boolean {
|
|
301
|
+
const target = metadata.controllerMetadata.target;
|
|
302
|
+
return !!(this.getMetadata(OPENAPI_METADATA_KEY.exclude, target) || this.getMetadata(OPENAPI_METADATA_KEY.exclude, target, this.methodKey(metadata)));
|
|
303
|
+
}
|
|
304
|
+
|
|
305
|
+
protected usesScheme(paths: Record<string, PathItemObject>, scheme: string): boolean {
|
|
306
|
+
return Object.values(paths).some(item =>
|
|
307
|
+
Object.values(item).some(operation => (operation.security || []).some((requirement: SecurityRequirementObject) => scheme in requirement)),
|
|
308
|
+
);
|
|
309
|
+
}
|
|
310
|
+
|
|
311
|
+
/** Path, query, header and cookie values are strings on the wire; a class or `any` there is documented as one. */
|
|
312
|
+
protected scalarSchema(schema: SchemaObject | undefined): SchemaObject {
|
|
313
|
+
if (!schema || schema.$ref || schema.type === 'object') {
|
|
314
|
+
return { type: 'string' };
|
|
315
|
+
}
|
|
316
|
+
return schema;
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
protected isClass(type: any): type is Constructor {
|
|
320
|
+
return typeof type === 'function' && !BUILT_IN_TYPES.includes(type);
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
protected parameterTypes(metadata: PathRouteMetadata): any[] {
|
|
324
|
+
return Reflect.getMetadata('design:paramtypes', metadata.controllerMetadata.target.prototype, this.methodKey(metadata)) || [];
|
|
325
|
+
}
|
|
326
|
+
|
|
327
|
+
protected methodKey(metadata: PathRouteMetadata): string | symbol {
|
|
328
|
+
return (metadata.methodMetadata as MethodMetadata).key;
|
|
329
|
+
}
|
|
330
|
+
|
|
331
|
+
protected getMetadata(key: string, target: any, propertyKey?: string | symbol): any {
|
|
332
|
+
return propertyKey === undefined ? Reflect.getMetadata(key, target) : Reflect.getMetadata(key, target, propertyKey);
|
|
333
|
+
}
|
|
334
|
+
}
|