@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,
} 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("GET", {
		operationId: "listUsersCommand",
		responses: {
			200: new Response(api, "ListUsersResponse", {
				description: "User 200 response",
				content: {
					contentType: "application/json",
					schema: users,
				},
			}),
		},
	})
	.addOperation("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("GET", {
		operationId: "getUserByIdCommand",
		responses: {
			200: new Response(api, "GetUserById", {
				description: "User 200 response",
				content: {
					contentType: "application/json",
					schema: user,
				},
			}),
		},
	})
	.addOperation("DELETE", {
		operationId: "deleteUserByIdCommand",
		security: userDeleteScopeReq,
	})
	.addOperation("HEAD", {
		operationId: "checkUserIdAvailableCommand",
		security: noSecurityRequirement,
	})
	.addOperation("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));