@block65/openapi-constructs
v3.0.1
Published
An experimental AWS Constructs based Open API schema builder
Downloads
253
Readme
@block65/openapi-constructs
An experimental AWS Constructs based Open API schema builder
Example
import {
Api,
OpenApiVersion,
Parameter,
Path,
Reference,
Response,
Schema,
SecurityRequirement,
SecurityScheme,
Server,
Tag,
HttpMethods,
} from '@block65/openapi-constructs';
const api = new Api({
openapi: OpenApiVersion.V3_1,
info: {
title: 'Example REST API',
version: '1.0.0',
},
});
new Server(api, 'ExampleServer', {
url: new URL('https://api.example.com'),
});
const httpBearerJwtScheme = new SecurityScheme(api, 'HttpBearerJwtScheme', {
type: 'http',
scheme: 'bearer',
bearerFormat: 'JWT',
});
new SecurityRequirement(api, 'AllScopes', {
securityScheme: httpBearerJwtScheme,
scopes: [],
});
const userTag = new Tag(api, 'UserTag', {
name: 'user',
});
const userDeleteScopeReq = new SecurityRequirement(api, 'UserDeleteScope', {
securityScheme: httpBearerJwtScheme,
scopes: ['users.delete'],
});
const noSecurityRequirement = new SecurityRequirement(api, 'NoSecurity');
const addressSchema = new Schema(api, 'Address', {
schema: {
type: 'object',
required: ['name'],
additionalProperties: false,
properties: {
postcode: {
type: 'integer',
format: 'int32',
minimum: 1000,
maximum: 9999,
},
},
},
});
const idSchema = new Schema(api, 'Id', {
schema: {
type: 'string',
minLength: 6,
maxLength: 6,
},
});
const user = new Schema(api, 'User', {
schema: {
type: 'object',
required: ['name'],
additionalProperties: false,
properties: {
userId: idSchema.referenceObject(),
name: {
type: 'string',
},
address: addressSchema.referenceObject(),
age: {
type: 'integer',
format: 'int32',
minimum: 0,
},
},
},
});
const updateUserRequest = new Schema(api, 'UpdateUserRequest', {
schema: {
type: 'object',
minProperties: 1,
additionalProperties: false,
properties: {
address: addressSchema.referenceObject(),
age: {
type: 'integer',
format: 'int32',
minimum: 0,
},
},
},
});
const createUserRequest = new Reference(user, 'CreateUserRequest');
const users = new Schema(api, 'Users', {
schema: {
type: 'array',
uniqueItems: true,
items: user.referenceObject(),
},
});
const userIdParameter = new Parameter(api, 'UserId', {
name: 'userId',
in: 'path',
required: true,
schema: idSchema,
});
new Path(api, {
path: '/users',
tags: new Set([userTag]),
})
.addOperation(HttpMethods.GET, {
operationId: 'listUsersCommand',
responses: {
200: new Response(api, 'ListUsersResponse', {
description: 'User 200 response',
content: {
contentType: 'application/json',
schema: users,
},
}),
},
})
.addOperation(HttpMethods.POST, {
operationId: 'createUserCommand',
requestBody: {
content: {
contentType: 'application/json',
schema: createUserRequest,
},
},
responses: {
200: new Response(api, 'CreateUserResponse', {
description: 'User 200 response',
content: {
contentType: 'application/json',
schema: users,
},
}),
},
});
new Path(api, {
path: '/users/{userId}',
parameters: [userIdParameter],
})
.addOperation(HttpMethods.GET, {
operationId: 'getUserByIdCommand',
responses: {
200: new Response(api, 'GetUserById', {
description: 'User 200 response',
content: {
contentType: 'application/json',
schema: user,
},
}),
},
})
.addOperation(HttpMethods.DELETE, {
operationId: 'deleteUserByIdCommand',
security: userDeleteScopeReq,
})
.addOperation(HttpMethods.HEAD, {
operationId: 'checkUserIdAvailableCommand',
security: noSecurityRequirement,
})
.addOperation(HttpMethods.POST, {
operationId: 'updateUserCommand',
requestBody: {
content: {
contentType: 'application/json',
schema: updateUserRequest,
},
},
responses: {
200: new Response(api, 'UpdateUserResponse', {
content: {
contentType: 'application/json',
schema: user,
},
}),
},
});
process.stdout.write(JSON.stringify(api.synth(), null, 2));