@celljs/openapi 0.0.0-stage → 4.3.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 +87 -2
- package/cell.yml +14 -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 +77 -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
package/README.md
CHANGED
|
@@ -1,3 +1,88 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Cell - OpenAPI Component
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Add `@celljs/openapi` to the dependencies to document the API of your `@celljs/mvc` controllers: the application serves an [OpenAPI 3.0](https://spec.openapis.org/oas/v3.0.3) document at `/openapi.json` and [Swagger UI](https://swagger.io/tools/swagger-ui/) at `/api-docs`. The document is built from the routes themselves (paths, `@Param` / `@Query` / `@Header` / `@Cookie` / `@Body`, TypeScript parameter and return types), so it stays in step with the code; `@Api*` decorators add what types cannot say. Example: [examples/openapi-app](https://github.com/cellbang/cell/tree/main/examples/openapi-app).
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
import { Body, Controller, Get, Param, Post, Query } from '@celljs/mvc/lib/node';
|
|
7
|
+
import { ApiOperation, ApiProperty, ApiPropertyOptional, ApiResponse, ApiTags } from '@celljs/openapi';
|
|
8
|
+
import { IsInt, IsOptional, IsString, Min } from 'class-validator';
|
|
9
|
+
|
|
10
|
+
export class CreatePet {
|
|
11
|
+
@IsString() // class-validator decorators become the schema: type, required, enum, length, range...
|
|
12
|
+
@ApiProperty({ example: 'Tom' }) // ...and @ApiProperty adds a description, an example or the type of an array
|
|
13
|
+
name: string;
|
|
14
|
+
|
|
15
|
+
@IsInt() @Min(0) @IsOptional()
|
|
16
|
+
age?: number;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
export class Pet extends CreatePet {
|
|
20
|
+
@ApiProperty()
|
|
21
|
+
id: number;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
@Controller('pets')
|
|
25
|
+
@ApiTags('Pets')
|
|
26
|
+
export class PetController {
|
|
27
|
+
@Get()
|
|
28
|
+
@ApiResponse({ type: [Pet] }) // async methods and arrays need the type: TypeScript emits only Promise / Array
|
|
29
|
+
list(@Query() query: PetQuery): Promise<Pet[]> { ... }
|
|
30
|
+
|
|
31
|
+
@Get(':id')
|
|
32
|
+
@ApiOperation({ summary: 'Find a pet' })
|
|
33
|
+
@ApiResponse({ status: 404, description: 'No such pet' })
|
|
34
|
+
get(@Param('id') id: number): Pet { ... } // the return type is the 200 response
|
|
35
|
+
|
|
36
|
+
@Post()
|
|
37
|
+
create(@Body() pet: CreatePet): Pet { ... } // the class of the body is the request schema
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
What goes into the document:
|
|
42
|
+
|
|
43
|
+
- **Paths**: every route of a controller, `:id` as `{id}`; an optional part (`/users(/:id)`) gives one path with it and one without. Routes with a RegExp path are left out.
|
|
44
|
+
- **Parameters**: `@Param('id')`, `@Query('q')`, `@Header('x-name')`, `@Cookie('name')` with the type of the parameter; `@Query() query: PetQuery` gives one query parameter per property of the class. Path parameters missing from the method are added as strings.
|
|
45
|
+
- **Body**: `@Body() pet: CreatePet` as an `application/json` body; named `@Body('name')` parameters as the properties of an object.
|
|
46
|
+
- **Responses**: the `@ApiResponse` ones (on the class for all its methods, or on the method); without a 2xx one, `200` with the return type. The content type follows the view: JSON by default, `text/plain` for `@Text()`, `text/html` for `@Html()`.
|
|
47
|
+
- **Schemas**: each class becomes an entry of `components.schemas`, referred to by `$ref`. Its properties are the ones with class-validator decorators (read from class-validator's metadata when it is installed, e.g. with [@celljs/validation](../validation/README.md); it is not a dependency of this package) or with `@ApiProperty`. A property is required unless it has `@IsOptional()` or `@ApiPropertyOptional()`.
|
|
48
|
+
- **Tags**: `@ApiTags`, otherwise the controller name without `Controller`.
|
|
49
|
+
|
|
50
|
+
| Decorator | On | Purpose |
|
|
51
|
+
| --- | --- | --- |
|
|
52
|
+
| `@ApiTags(...tags)` | class, method | Groups operations |
|
|
53
|
+
| `@ApiOperation({ summary, description, operationId, deprecated })` | method | Describes an operation; `operationId` defaults to `<Class>_<method>` |
|
|
54
|
+
| `@ApiResponse({ status, description, type, schema, contentType })` | class, method | A response; repeat it per status; `type: [Pet]` for a list |
|
|
55
|
+
| `@ApiProperty(options)` / `@ApiPropertyOptional(options)` | property | A property of a request or response class; `type`, `enum` (a list or a TypeScript enum), `description`, `example`, `format` and any other schema field |
|
|
56
|
+
| `@ApiParam` / `@ApiQuery` / `@ApiHeader({ name, ... })` | method | Describes a parameter, or documents one the method reads from the request itself |
|
|
57
|
+
| `@ApiSecurity(name, scopes?)` / `@ApiBearerAuth()` | class, method | Requires a security scheme; `bearer` is declared for `@ApiBearerAuth()` when `components.securitySchemes` has none |
|
|
58
|
+
| `@ApiExclude()` | class, method | Leaves it out of the document |
|
|
59
|
+
|
|
60
|
+
## Configuration
|
|
61
|
+
|
|
62
|
+
```yaml
|
|
63
|
+
backend:
|
|
64
|
+
cell:
|
|
65
|
+
openapi:
|
|
66
|
+
enabled: true # false: serve neither the document nor the UI
|
|
67
|
+
url: /openapi.json # under cell.server.path
|
|
68
|
+
ui:
|
|
69
|
+
enabled: true
|
|
70
|
+
url: /api-docs
|
|
71
|
+
cdn: https://cdn.jsdelivr.net/npm/swagger-ui-dist@5 # where the page loads Swagger UI from
|
|
72
|
+
document: # merged into the generated document
|
|
73
|
+
openapi: 3.0.3
|
|
74
|
+
info:
|
|
75
|
+
title: Pet Store
|
|
76
|
+
version: 1.0.0
|
|
77
|
+
servers:
|
|
78
|
+
- url: https://api.example.com
|
|
79
|
+
components:
|
|
80
|
+
securitySchemes:
|
|
81
|
+
apiKey: { type: apiKey, in: header, name: X-API-Key }
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
The document and the page answer GET requests no controller answered, so a route of the application with the same path wins and other requests pay nothing. They are public unless [@celljs/security](../security/README.md) protects them; to hide them in production, set `enabled: false` in the production config (`cell.production.yml`).
|
|
85
|
+
|
|
86
|
+
To write the document to a file without starting a server (for API clients, code generators or a review), fetch it from `createTestApp()` of `@celljs/cli`, as `scripts/export-openapi.ts` of the example does.
|
|
87
|
+
|
|
88
|
+
`OpenApiDocumentProvider` (`@celljs/openapi/lib/node`) gives the document in code; rebind it to change how it is built.
|
package/cell.yml
ADDED
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
import type { ParameterLocation, SchemaObject, TypeRef } from './openapi-protocol.js';
|
|
2
|
+
export interface ApiOperationOptions {
|
|
3
|
+
summary?: string;
|
|
4
|
+
description?: string;
|
|
5
|
+
/** Default: `<ControllerClass>_<method>`. */
|
|
6
|
+
operationId?: string;
|
|
7
|
+
deprecated?: boolean;
|
|
8
|
+
}
|
|
9
|
+
export interface ApiResponseOptions {
|
|
10
|
+
/** Default: 200. */
|
|
11
|
+
status?: number | 'default';
|
|
12
|
+
description?: string;
|
|
13
|
+
/** Type of the body; `[User]` for a list. */
|
|
14
|
+
type?: TypeRef;
|
|
15
|
+
/** A schema written by hand; wins over `type`. */
|
|
16
|
+
schema?: SchemaObject;
|
|
17
|
+
/** Default: by the view of the method (`application/json`, `text/plain` for `@Text()`...). */
|
|
18
|
+
contentType?: string;
|
|
19
|
+
}
|
|
20
|
+
export type ApiPropertyOptions = Omit<SchemaObject, 'type' | 'required' | 'enum' | 'items'> & {
|
|
21
|
+
/** Default: the TypeScript type of the property (`design:type`); needed for arrays (`[Item]`). */
|
|
22
|
+
type?: TypeRef;
|
|
23
|
+
/** Default: true. */
|
|
24
|
+
required?: boolean;
|
|
25
|
+
/** Values, or a TypeScript enum. */
|
|
26
|
+
enum?: any[] | Record<string, any>;
|
|
27
|
+
items?: SchemaObject;
|
|
28
|
+
};
|
|
29
|
+
export type ApiParameterOptions = Omit<ApiPropertyOptions, 'description' | 'example' | 'deprecated'> & {
|
|
30
|
+
name: string;
|
|
31
|
+
description?: string;
|
|
32
|
+
example?: any;
|
|
33
|
+
deprecated?: boolean;
|
|
34
|
+
};
|
|
35
|
+
export interface ApiParameterMetadata extends ApiParameterOptions {
|
|
36
|
+
in: ParameterLocation;
|
|
37
|
+
}
|
|
38
|
+
export interface ApiPropertyMetadata {
|
|
39
|
+
key: string;
|
|
40
|
+
options: ApiPropertyOptions;
|
|
41
|
+
}
|
|
42
|
+
/** Groups the operations of a controller or a method in the UI. Default: the controller name without `Controller`. */
|
|
43
|
+
export declare function ApiTags(...tags: string[]): ClassDecorator & MethodDecorator;
|
|
44
|
+
export declare function ApiOperation(options: ApiOperationOptions): MethodDecorator;
|
|
45
|
+
/** A possible response; on a controller it applies to all its methods. Repeat it for several statuses. */
|
|
46
|
+
export declare function ApiResponse(options: ApiResponseOptions): ClassDecorator & MethodDecorator;
|
|
47
|
+
/** Describes a property of a request or response class. Properties with class-validator decorators are found without it. */
|
|
48
|
+
export declare function ApiProperty(options?: ApiPropertyOptions): PropertyDecorator;
|
|
49
|
+
export declare function ApiPropertyOptional(options?: ApiPropertyOptions): PropertyDecorator;
|
|
50
|
+
/** Describes a path parameter; it is found from the route without it. */
|
|
51
|
+
export declare function ApiParam(options: ApiParameterOptions): MethodDecorator;
|
|
52
|
+
/** Describes a query parameter, or documents one the method reads from the request itself. */
|
|
53
|
+
export declare function ApiQuery(options: ApiParameterOptions): MethodDecorator;
|
|
54
|
+
export declare function ApiHeader(options: ApiParameterOptions): MethodDecorator;
|
|
55
|
+
/** Requires the security scheme `name` (declared in `cell.openapi.document.components.securitySchemes`). */
|
|
56
|
+
export declare function ApiSecurity(name: string, scopes?: string[]): ClassDecorator & MethodDecorator;
|
|
57
|
+
/** Requires a bearer token (`Authorization: Bearer ...`); the scheme `bearer` is declared when it is missing. */
|
|
58
|
+
export declare function ApiBearerAuth(name?: string): ClassDecorator & MethodDecorator;
|
|
59
|
+
/** Leaves a controller or a method out of the document. */
|
|
60
|
+
export declare function ApiExclude(): ClassDecorator & MethodDecorator;
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
import { DEFAULT_BEARER_SCHEME, OPENAPI_METADATA_KEY } from './constants.js';
|
|
2
|
+
function defineList(key, value, target, propertyKey) {
|
|
3
|
+
const list = (propertyKey === undefined ? Reflect.getOwnMetadata(key, target) : Reflect.getOwnMetadata(key, target, propertyKey)) || [];
|
|
4
|
+
list.push(value);
|
|
5
|
+
if (propertyKey === undefined) {
|
|
6
|
+
Reflect.defineMetadata(key, list, target);
|
|
7
|
+
}
|
|
8
|
+
else {
|
|
9
|
+
Reflect.defineMetadata(key, list, target, propertyKey);
|
|
10
|
+
}
|
|
11
|
+
}
|
|
12
|
+
/** A decorator for a controller (`target` is the class) or one of its methods (metadata goes on the class with the method name). */
|
|
13
|
+
function classOrMethod(key, value, list) {
|
|
14
|
+
return ((target, propertyKey) => {
|
|
15
|
+
const owner = propertyKey === undefined ? target : target.constructor;
|
|
16
|
+
if (list) {
|
|
17
|
+
defineList(key, value, owner, propertyKey);
|
|
18
|
+
}
|
|
19
|
+
else if (propertyKey === undefined) {
|
|
20
|
+
Reflect.defineMetadata(key, value, owner);
|
|
21
|
+
}
|
|
22
|
+
else {
|
|
23
|
+
Reflect.defineMetadata(key, value, owner, propertyKey);
|
|
24
|
+
}
|
|
25
|
+
});
|
|
26
|
+
}
|
|
27
|
+
/** Groups the operations of a controller or a method in the UI. Default: the controller name without `Controller`. */
|
|
28
|
+
export function ApiTags(...tags) {
|
|
29
|
+
return classOrMethod(OPENAPI_METADATA_KEY.tags, tags, false);
|
|
30
|
+
}
|
|
31
|
+
export function ApiOperation(options) {
|
|
32
|
+
return classOrMethod(OPENAPI_METADATA_KEY.operation, options, false);
|
|
33
|
+
}
|
|
34
|
+
/** A possible response; on a controller it applies to all its methods. Repeat it for several statuses. */
|
|
35
|
+
export function ApiResponse(options) {
|
|
36
|
+
return classOrMethod(OPENAPI_METADATA_KEY.responses, options, true);
|
|
37
|
+
}
|
|
38
|
+
/** Describes a property of a request or response class. Properties with class-validator decorators are found without it. */
|
|
39
|
+
export function ApiProperty(options = {}) {
|
|
40
|
+
return (target, propertyKey) => {
|
|
41
|
+
defineList(OPENAPI_METADATA_KEY.properties, { key: propertyKey.toString(), options }, target.constructor);
|
|
42
|
+
};
|
|
43
|
+
}
|
|
44
|
+
export function ApiPropertyOptional(options = {}) {
|
|
45
|
+
return ApiProperty({ ...options, required: false });
|
|
46
|
+
}
|
|
47
|
+
function parameter(location, options) {
|
|
48
|
+
return classOrMethod(OPENAPI_METADATA_KEY.parameters, { ...options, in: location }, true);
|
|
49
|
+
}
|
|
50
|
+
/** Describes a path parameter; it is found from the route without it. */
|
|
51
|
+
export function ApiParam(options) {
|
|
52
|
+
return parameter('path', options);
|
|
53
|
+
}
|
|
54
|
+
/** Describes a query parameter, or documents one the method reads from the request itself. */
|
|
55
|
+
export function ApiQuery(options) {
|
|
56
|
+
return parameter('query', options);
|
|
57
|
+
}
|
|
58
|
+
export function ApiHeader(options) {
|
|
59
|
+
return parameter('header', options);
|
|
60
|
+
}
|
|
61
|
+
/** Requires the security scheme `name` (declared in `cell.openapi.document.components.securitySchemes`). */
|
|
62
|
+
export function ApiSecurity(name, scopes = []) {
|
|
63
|
+
return classOrMethod(OPENAPI_METADATA_KEY.security, { [name]: scopes }, true);
|
|
64
|
+
}
|
|
65
|
+
/** Requires a bearer token (`Authorization: Bearer ...`); the scheme `bearer` is declared when it is missing. */
|
|
66
|
+
export function ApiBearerAuth(name = DEFAULT_BEARER_SCHEME) {
|
|
67
|
+
return ApiSecurity(name);
|
|
68
|
+
}
|
|
69
|
+
/** Leaves a controller or a method out of the document. */
|
|
70
|
+
export function ApiExclude() {
|
|
71
|
+
return classOrMethod(OPENAPI_METADATA_KEY.exclude, true, false);
|
|
72
|
+
}
|
|
73
|
+
//# sourceMappingURL=annotation.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"annotation.js","sourceRoot":"","sources":["../../src/common/annotation.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
export declare const OPENAPI_METADATA_KEY: {
|
|
2
|
+
tags: string;
|
|
3
|
+
operation: string;
|
|
4
|
+
responses: string;
|
|
5
|
+
parameters: string;
|
|
6
|
+
properties: string;
|
|
7
|
+
security: string;
|
|
8
|
+
exclude: string;
|
|
9
|
+
};
|
|
10
|
+
/** Name of the security scheme that `@ApiBearerAuth()` refers to when none is given. */
|
|
11
|
+
export declare const DEFAULT_BEARER_SCHEME = "bearer";
|
|
@@ -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
|
+
/** Name of the security scheme that `@ApiBearerAuth()` refers to when none is given. */
|
|
11
|
+
export const DEFAULT_BEARER_SCHEME = 'bearer';
|
|
12
|
+
//# sourceMappingURL=constants.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/common/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAChC,IAAI,EAAE,mBAAmB;IACzB,SAAS,EAAE,wBAAwB;IACnC,SAAS,EAAE,wBAAwB;IACnC,UAAU,EAAE,yBAAyB;IACrC,UAAU,EAAE,yBAAyB;IACrC,QAAQ,EAAE,uBAAuB;IACjC,OAAO,EAAE,sBAAsB;CAClC,CAAC;AAEF,wFAAwF;AACxF,MAAM,CAAC,MAAM,qBAAqB,GAAG,QAAQ,CAAC"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC"}
|
|
@@ -0,0 +1,143 @@
|
|
|
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 `cell.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?: {
|
|
14
|
+
url: string;
|
|
15
|
+
description?: string;
|
|
16
|
+
};
|
|
17
|
+
[extension: string]: any;
|
|
18
|
+
}
|
|
19
|
+
export interface InfoObject {
|
|
20
|
+
title: string;
|
|
21
|
+
version: string;
|
|
22
|
+
description?: string;
|
|
23
|
+
[extension: string]: any;
|
|
24
|
+
}
|
|
25
|
+
export interface ServerObject {
|
|
26
|
+
url: string;
|
|
27
|
+
description?: string;
|
|
28
|
+
[extension: string]: any;
|
|
29
|
+
}
|
|
30
|
+
export interface TagObject {
|
|
31
|
+
name: string;
|
|
32
|
+
description?: string;
|
|
33
|
+
[extension: string]: any;
|
|
34
|
+
}
|
|
35
|
+
export type PathItemObject = Record<string, OperationObject>;
|
|
36
|
+
export interface OperationObject {
|
|
37
|
+
tags?: string[];
|
|
38
|
+
summary?: string;
|
|
39
|
+
description?: string;
|
|
40
|
+
operationId?: string;
|
|
41
|
+
parameters?: ParameterObject[];
|
|
42
|
+
requestBody?: RequestBodyObject;
|
|
43
|
+
responses: Record<string, ResponseObject>;
|
|
44
|
+
deprecated?: boolean;
|
|
45
|
+
security?: SecurityRequirementObject[];
|
|
46
|
+
[extension: string]: any;
|
|
47
|
+
}
|
|
48
|
+
export type ParameterLocation = 'path' | 'query' | 'header' | 'cookie';
|
|
49
|
+
export interface ParameterObject {
|
|
50
|
+
name: string;
|
|
51
|
+
in: ParameterLocation;
|
|
52
|
+
description?: string;
|
|
53
|
+
required?: boolean;
|
|
54
|
+
deprecated?: boolean;
|
|
55
|
+
schema?: SchemaObject;
|
|
56
|
+
example?: any;
|
|
57
|
+
[extension: string]: any;
|
|
58
|
+
}
|
|
59
|
+
export interface RequestBodyObject {
|
|
60
|
+
description?: string;
|
|
61
|
+
required?: boolean;
|
|
62
|
+
content: Record<string, MediaTypeObject>;
|
|
63
|
+
}
|
|
64
|
+
export interface MediaTypeObject {
|
|
65
|
+
schema?: SchemaObject;
|
|
66
|
+
example?: any;
|
|
67
|
+
}
|
|
68
|
+
export interface ResponseObject {
|
|
69
|
+
description: string;
|
|
70
|
+
content?: Record<string, MediaTypeObject>;
|
|
71
|
+
headers?: Record<string, {
|
|
72
|
+
description?: string;
|
|
73
|
+
schema?: SchemaObject;
|
|
74
|
+
}>;
|
|
75
|
+
}
|
|
76
|
+
export interface SchemaObject {
|
|
77
|
+
$ref?: string;
|
|
78
|
+
type?: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object';
|
|
79
|
+
format?: string;
|
|
80
|
+
items?: SchemaObject;
|
|
81
|
+
properties?: Record<string, SchemaObject>;
|
|
82
|
+
required?: string[];
|
|
83
|
+
additionalProperties?: boolean | SchemaObject;
|
|
84
|
+
enum?: any[];
|
|
85
|
+
description?: string;
|
|
86
|
+
example?: any;
|
|
87
|
+
default?: any;
|
|
88
|
+
nullable?: boolean;
|
|
89
|
+
deprecated?: boolean;
|
|
90
|
+
readOnly?: boolean;
|
|
91
|
+
writeOnly?: boolean;
|
|
92
|
+
minimum?: number;
|
|
93
|
+
maximum?: number;
|
|
94
|
+
exclusiveMinimum?: boolean;
|
|
95
|
+
exclusiveMaximum?: boolean;
|
|
96
|
+
minLength?: number;
|
|
97
|
+
maxLength?: number;
|
|
98
|
+
pattern?: string;
|
|
99
|
+
minItems?: number;
|
|
100
|
+
maxItems?: number;
|
|
101
|
+
oneOf?: SchemaObject[];
|
|
102
|
+
allOf?: SchemaObject[];
|
|
103
|
+
anyOf?: SchemaObject[];
|
|
104
|
+
[extension: string]: any;
|
|
105
|
+
}
|
|
106
|
+
export interface ComponentsObject {
|
|
107
|
+
schemas?: Record<string, SchemaObject>;
|
|
108
|
+
securitySchemes?: Record<string, SecuritySchemeObject>;
|
|
109
|
+
[extension: string]: any;
|
|
110
|
+
}
|
|
111
|
+
export interface SecuritySchemeObject {
|
|
112
|
+
type: 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';
|
|
113
|
+
description?: string;
|
|
114
|
+
name?: string;
|
|
115
|
+
in?: 'query' | 'header' | 'cookie';
|
|
116
|
+
scheme?: string;
|
|
117
|
+
bearerFormat?: string;
|
|
118
|
+
[extension: string]: any;
|
|
119
|
+
}
|
|
120
|
+
export type SecurityRequirementObject = Record<string, string[]>;
|
|
121
|
+
/**
|
|
122
|
+
* What describes the type of a property, a parameter, a body or a response:
|
|
123
|
+
* a class (`User`, `String`, `Number`, `Boolean`, `Date`), an array of one (`[User]`) or an OpenAPI type name (`'integer'`).
|
|
124
|
+
*/
|
|
125
|
+
export type TypeRef = Constructor | [Constructor] | [string] | NonNullable<SchemaObject['type']>;
|
|
126
|
+
/** A class, including the built-in ones (`String`, `Date`...) and abstract classes. */
|
|
127
|
+
export type Constructor = abstract new (...args: any[]) => any;
|
|
128
|
+
/** `cell.openapi` in cell.yml (backend). */
|
|
129
|
+
export interface OpenApiOptions {
|
|
130
|
+
/** false: neither the document nor the UI is served. */
|
|
131
|
+
enabled: boolean;
|
|
132
|
+
/** Path of the JSON document, under `cell.server.path`. */
|
|
133
|
+
url: string;
|
|
134
|
+
ui: {
|
|
135
|
+
enabled: boolean;
|
|
136
|
+
/** Path of the Swagger UI page, under `cell.server.path`. */
|
|
137
|
+
url: string;
|
|
138
|
+
/** Where the page loads swagger-ui-dist from (swagger-ui.css, swagger-ui-bundle.js). */
|
|
139
|
+
cdn: string;
|
|
140
|
+
};
|
|
141
|
+
/** Merged into the generated document: info, servers, tags, components.securitySchemes, security... */
|
|
142
|
+
document: Partial<OpenApiDocument>;
|
|
143
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"openapi-protocol.js","sourceRoot":"","sources":["../../src/common/openapi-protocol.ts"],"names":[],"mappings":""}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
export * from './openapi-document-provider.js';
|
|
2
|
+
export * from './openapi-middleware.js';
|
|
3
|
+
export * from './openapi-node-protocol.js';
|
|
4
|
+
export * from './openapi-path-util.js';
|
|
5
|
+
export * from './schema-builder.js';
|
|
6
|
+
export * from './swagger-ui.js';
|
|
7
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"module.js","sourceRoot":"","sources":["../../src/node/module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,SAAS,CAAC;AAEjB,eAAe,QAAQ,EAAE,CAAC"}
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import { type PathRouteMetadata, type Route, RouteProvider } from '@celljs/mvc/lib/node';
|
|
2
|
+
import { type Constructor, type OpenApiDocument, type OpenApiOptions, type OperationObject, type ParameterObject, type PathItemObject, type RequestBodyObject, type ResponseObject, type SchemaObject } from '../common/index.js';
|
|
3
|
+
import { OpenApiDocumentProvider } from './openapi-node-protocol.js';
|
|
4
|
+
import { SchemaBuilder } from './schema-builder.js';
|
|
5
|
+
/** What one route of a controller method contributes, before it is placed under its paths. */
|
|
6
|
+
interface RouteOperation {
|
|
7
|
+
method: string;
|
|
8
|
+
pattern: string;
|
|
9
|
+
operation: OperationObject;
|
|
10
|
+
}
|
|
11
|
+
/**
|
|
12
|
+
* Builds the OpenAPI document from the routes of `@celljs/mvc` (the same metadata that serves the requests)
|
|
13
|
+
* and the `@Api*` decorators; `cell.openapi.document` is merged over it.
|
|
14
|
+
*/
|
|
15
|
+
export declare class OpenApiDocumentProviderImpl implements OpenApiDocumentProvider {
|
|
16
|
+
protected readonly routeProvider: RouteProvider;
|
|
17
|
+
protected readonly options: OpenApiOptions;
|
|
18
|
+
protected readonly defaultViewName: string;
|
|
19
|
+
protected document?: Promise<OpenApiDocument>;
|
|
20
|
+
provide(): Promise<OpenApiDocument>;
|
|
21
|
+
protected build(route: Route): OpenApiDocument;
|
|
22
|
+
/** Places the operations under their OpenAPI paths, sorted by path then by method; operation ids stay unique. */
|
|
23
|
+
protected buildPaths(routes: RouteOperation[]): Record<string, PathItemObject>;
|
|
24
|
+
/** Keeps the path parameters of this path (optional parts differ), adds the undeclared ones as strings. */
|
|
25
|
+
protected withPathParameters(operation: OperationObject, names: string[], operationIds: Set<string>): OperationObject;
|
|
26
|
+
protected buildOperation(metadata: PathRouteMetadata, schemas: SchemaBuilder): OperationObject;
|
|
27
|
+
protected buildParameters(metadata: PathRouteMetadata, schemas: SchemaBuilder): ParameterObject[];
|
|
28
|
+
protected buildRequestBody(metadata: PathRouteMetadata, schemas: SchemaBuilder): RequestBodyObject | undefined;
|
|
29
|
+
protected buildResponses(metadata: PathRouteMetadata, schemas: SchemaBuilder): Record<string, ResponseObject>;
|
|
30
|
+
protected isExcluded(metadata: PathRouteMetadata): boolean;
|
|
31
|
+
protected usesScheme(paths: Record<string, PathItemObject>, scheme: string): boolean;
|
|
32
|
+
/** Path, query, header and cookie values are strings on the wire; a class or `any` there is documented as one. */
|
|
33
|
+
protected scalarSchema(schema: SchemaObject | undefined): SchemaObject;
|
|
34
|
+
protected isClass(type: any): type is Constructor;
|
|
35
|
+
protected parameterTypes(metadata: PathRouteMetadata): any[];
|
|
36
|
+
protected methodKey(metadata: PathRouteMetadata): string | symbol;
|
|
37
|
+
protected getMetadata(key: string, target: any, propertyKey?: string | symbol): any;
|
|
38
|
+
}
|
|
39
|
+
export {};
|