@seshuk/payload-plugin-openapi 0.1.0

package/dist/spec/paths/auth.js

@@ -0,0 +1,285 @@
+import { makeT } from "../../translations/index.js";
+import { ERRORS, errorResponses, jsonBody, jsonResponse, messageResponse } from "../components.js";
+import { refTo, schemaName } from "../names.js";
+import { authTagName } from "../tags.js";
+const identifierProps = (auth)=>{
+    const loginWithUsername = Boolean(auth?.loginWithUsername);
+    const usernameOnly = 'object' == typeof auth?.loginWithUsername && false === auth.loginWithUsername.requireEmail;
+    if (loginWithUsername && usernameOnly) return {
+        properties: {
+            username: {
+                type: 'string'
+            }
+        },
+        required: [
+            'username'
+        ]
+    };
+    if (loginWithUsername) return {
+        properties: {
+            email: {
+                type: 'string',
+                format: 'email'
+            },
+            username: {
+                type: 'string'
+            }
+        },
+        required: []
+    };
+    return {
+        properties: {
+            email: {
+                type: 'string',
+                format: 'email'
+            }
+        },
+        required: [
+            'email'
+        ]
+    };
+};
+const buildAuthPaths = ({ collection, ctx, includeAdmin, nestedTags })=>{
+    const auth = collection.auth;
+    if (!auth || auth.disableLocalStrategy) return {};
+    const t = makeT(ctx.i18n);
+    const name = schemaName(collection.slug);
+    const base = `${ctx.apiRoute}/${collection.slug}`;
+    const tag = [
+        nestedTags ? authTagName(name) : name
+    ];
+    const ident = identifierProps(auth);
+    const userRef = {
+        $ref: refTo(name)
+    };
+    const op = (operationId, codes, extra)=>({
+            tags: tag,
+            operationId,
+            ...extra,
+            responses: {
+                ...extra.responses,
+                ...errorResponses(codes, t)
+            }
+        });
+    const paths = {
+        [`${base}/login`]: {
+            post: op(`login${name}`, ERRORS.login, {
+                requestBody: jsonBody({
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        ...ident.properties,
+                        password: {
+                            type: 'string'
+                        }
+                    },
+                    required: [
+                        ...ident.required,
+                        'password'
+                    ]
+                }),
+                responses: {
+                    200: jsonResponse(t('authLogin'), {
+                        type: 'object',
+                        properties: {
+                            message: {
+                                type: 'string'
+                            },
+                            user: userRef,
+                            token: {
+                                type: 'string'
+                            },
+                            exp: {
+                                type: 'integer'
+                            }
+                        }
+                    })
+                }
+            })
+        },
+        [`${base}/logout`]: {
+            post: op(`logout${name}`, ERRORS.session, {
+                responses: messageResponse(t('authLogout'))
+            })
+        },
+        [`${base}/me`]: {
+            get: op(`me${name}`, ERRORS.session, {
+                responses: {
+                    200: jsonResponse(t('authMe'), {
+                        type: 'object',
+                        properties: {
+                            user: userRef,
+                            collection: {
+                                type: 'string'
+                            },
+                            token: {
+                                type: 'string'
+                            },
+                            exp: {
+                                type: 'integer'
+                            }
+                        }
+                    })
+                }
+            })
+        },
+        [`${base}/refresh-token`]: {
+            post: op(`refreshToken${name}`, ERRORS.session, {
+                responses: {
+                    200: jsonResponse(t('authRefreshToken'), {
+                        type: 'object',
+                        properties: {
+                            message: {
+                                type: 'string'
+                            },
+                            refreshedToken: {
+                                type: 'string'
+                            },
+                            exp: {
+                                type: 'integer'
+                            },
+                            user: userRef
+                        }
+                    })
+                }
+            })
+        },
+        [`${base}/forgot-password`]: {
+            post: op(`forgotPassword${name}`, ERRORS.authAction, {
+                requestBody: jsonBody({
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        email: {
+                            type: 'string',
+                            format: 'email'
+                        }
+                    },
+                    required: [
+                        'email'
+                    ]
+                }),
+                responses: messageResponse(t('authForgotPassword'))
+            })
+        },
+        [`${base}/reset-password`]: {
+            post: op(`resetPassword${name}`, ERRORS.authAction, {
+                requestBody: jsonBody({
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        token: {
+                            type: 'string'
+                        },
+                        password: {
+                            type: 'string'
+                        }
+                    },
+                    required: [
+                        'token',
+                        'password'
+                    ]
+                }),
+                responses: {
+                    200: jsonResponse(t('authResetPassword'), {
+                        type: 'object',
+                        properties: {
+                            message: {
+                                type: 'string'
+                            },
+                            token: {
+                                type: 'string'
+                            },
+                            user: userRef
+                        }
+                    })
+                }
+            })
+        }
+    };
+    if (includeAdmin) {
+        paths[`${base}/first-register`] = {
+            post: op(`firstRegister${name}`, ERRORS.create, {
+                requestBody: jsonBody({
+                    $ref: refTo(`${name}Create`)
+                }),
+                responses: {
+                    200: jsonResponse(t('authFirstRegister'), {
+                        type: 'object',
+                        properties: {
+                            message: {
+                                type: 'string'
+                            },
+                            user: userRef,
+                            token: {
+                                type: 'string'
+                            },
+                            exp: {
+                                type: 'integer'
+                            }
+                        }
+                    })
+                }
+            })
+        };
+        paths[`${base}/init`] = {
+            get: op(`init${name}`, ERRORS.session, {
+                responses: {
+                    200: jsonResponse(t('authInit'), {
+                        type: 'object',
+                        properties: {
+                            initialized: {
+                                type: 'boolean'
+                            }
+                        }
+                    })
+                }
+            })
+        };
+        paths[`${base}/access`] = {
+            get: op(`access${name}`, ERRORS.session, {
+                responses: {
+                    200: jsonResponse(t('authAccess'), {
+                        type: 'object',
+                        additionalProperties: true
+                    })
+                }
+            })
+        };
+    }
+    if (auth.maxLoginAttempts && auth.maxLoginAttempts > 0) paths[`${base}/unlock`] = {
+        post: op(`unlock${name}`, ERRORS.authAction, {
+            requestBody: jsonBody({
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    email: {
+                        type: 'string',
+                        format: 'email'
+                    }
+                },
+                required: [
+                    'email'
+                ]
+            }),
+            responses: messageResponse(t('authUnlock'))
+        })
+    };
+    if (auth.verify) paths[`${base}/verify/{id}`] = {
+        post: op(`verify${name}`, ERRORS.authAction, {
+            parameters: [
+                {
+                    name: 'id',
+                    in: 'path',
+                    required: true,
+                    schema: {
+                        type: 'string'
+                    }
+                }
+            ],
+            responses: messageResponse(t('authVerify'))
+        })
+    };
+    return paths;
+};
+export { buildAuthPaths };

package/dist/spec/paths/collections.d.ts

@@ -0,0 +1,7 @@
+import type { SanitizedCollectionConfig } from 'payload';
+import type { PathsObject } from '@scalar/openapi-types/3.2';
+import type { BuildContext } from '../../types.js';
+export declare const buildCollectionPaths: ({ collection, ctx, }: {
+    collection: SanitizedCollectionConfig;
+    ctx: BuildContext;
+}) => PathsObject;

package/dist/spec/paths/collections.js

@@ -0,0 +1,261 @@
+import { makeT } from "../../translations/index.js";
+import { ERRORS, SECURITY_SCHEME_NAME, errorResponses, isOpenToPublic, jsonOk, uploadRequestBody } from "../components.js";
+import { createSchemaName, listSchemaName, refTo, schemaName, updateSchemaName } from "../names.js";
+import { buildListParams, buildParamSchemas, commonReadParams } from "../params.js";
+const buildCollectionPaths = ({ collection, ctx })=>{
+    const t = makeT(ctx.i18n);
+    const name = schemaName(collection.slug);
+    const base = `${ctx.apiRoute}/${collection.slug}`;
+    const docRef = {
+        $ref: refTo(name)
+    };
+    const listRef = {
+        $ref: refTo(listSchemaName(name))
+    };
+    const createRef = {
+        $ref: refTo(createSchemaName(name))
+    };
+    const updateRef = {
+        $ref: refTo(updateSchemaName(name))
+    };
+    const idType = 'number' === ctx.defaultIDType ? 'integer' : 'string';
+    const secured = isOpenToPublic(collection.access?.read) ? void 0 : [
+        {
+            [SECURITY_SCHEME_NAME]: []
+        }
+    ];
+    const allowBulk = true !== collection.disableBulkEdit;
+    const allowDuplicate = true !== collection.disableDuplicate;
+    const paramSchemas = buildParamSchemas({
+        fields: collection.fields,
+        ctx
+    });
+    const refs = {
+        select: true,
+        populate: Boolean(paramSchemas.populate),
+        joins: Boolean(paramSchemas.joins)
+    };
+    const isUpload = Boolean(collection.upload);
+    const fileRequiredOnCreate = 'object' == typeof collection.upload ? false !== collection.upload.filesRequiredOnCreate : true;
+    const requestBody = (ref, fileRequired)=>isUpload ? uploadRequestBody({
+            bodyRef: ref,
+            fileRequired,
+            t
+        }) : {
+            content: {
+                'application/json': {
+                    schema: ref
+                }
+            }
+        };
+    const mutationSchema = {
+        type: 'object',
+        properties: {
+            message: {
+                type: 'string'
+            },
+            doc: docRef
+        }
+    };
+    const listResponse = {
+        ...jsonOk(t('collectionList'), listRef),
+        ...errorResponses(ERRORS.list, t)
+    };
+    const findByIdResponse = {
+        ...jsonOk(t('collectionDoc'), docRef),
+        ...errorResponses(ERRORS.read, t)
+    };
+    const createResponse = {
+        ...jsonOk(t('collectionCreated'), mutationSchema),
+        ...errorResponses(ERRORS.create, t)
+    };
+    const updateResponse = {
+        ...jsonOk(t('collectionUpdated'), mutationSchema),
+        ...errorResponses(ERRORS.update, t)
+    };
+    const deleteResponse = {
+        ...jsonOk(t('collectionDeleted'), mutationSchema),
+        ...errorResponses(ERRORS["delete"], t)
+    };
+    const bulkSchema = {
+        type: 'object',
+        properties: {
+            message: {
+                type: 'string'
+            },
+            docs: {
+                type: 'array',
+                items: docRef
+            },
+            errors: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        message: {
+                            type: 'string'
+                        },
+                        id: {
+                            type: idType
+                        }
+                    }
+                }
+            }
+        }
+    };
+    const bulkUpdateResponse = {
+        ...jsonOk(t('collectionBulkUpdate'), bulkSchema),
+        ...errorResponses(ERRORS.update, t)
+    };
+    const bulkDeleteResponse = {
+        ...jsonOk(t('collectionBulkDelete'), bulkSchema),
+        ...errorResponses(ERRORS["delete"], t)
+    };
+    const countResponse = {
+        ...jsonOk(t('collectionCount'), {
+            type: 'object',
+            properties: {
+                totalDocs: {
+                    type: 'integer'
+                }
+            }
+        }),
+        ...errorResponses(ERRORS.list, t)
+    };
+    const whereParameter = buildListParams({
+        base: name,
+        fields: collection.fields,
+        ctx,
+        refs
+    }).find((p)=>'where' === p.name);
+    const bulkParams = whereParameter ? [
+        whereParameter
+    ] : [];
+    const bulkOps = allowBulk ? {
+        patch: {
+            tags: [
+                name
+            ],
+            operationId: `update${name}`,
+            parameters: bulkParams,
+            requestBody: requestBody(updateRef, false),
+            responses: bulkUpdateResponse,
+            security: secured
+        },
+        delete: {
+            tags: [
+                name
+            ],
+            operationId: `delete${name}`,
+            parameters: bulkParams,
+            responses: bulkDeleteResponse,
+            security: secured
+        }
+    } : {};
+    const paths = {
+        [base]: {
+            get: {
+                tags: [
+                    name
+                ],
+                operationId: `find${name}`,
+                parameters: buildListParams({
+                    base: name,
+                    fields: collection.fields,
+                    ctx,
+                    refs
+                }),
+                responses: listResponse,
+                security: secured
+            },
+            post: {
+                tags: [
+                    name
+                ],
+                operationId: `create${name}`,
+                requestBody: requestBody(createRef, fileRequiredOnCreate),
+                responses: createResponse,
+                security: secured
+            },
+            ...bulkOps
+        },
+        [`${base}/count`]: {
+            get: {
+                tags: [
+                    name
+                ],
+                operationId: `count${name}`,
+                parameters: bulkParams,
+                responses: countResponse,
+                security: secured
+            }
+        },
+        [`${base}/{id}`]: {
+            parameters: [
+                {
+                    name: 'id',
+                    in: 'path',
+                    required: true,
+                    schema: {
+                        type: idType
+                    }
+                }
+            ],
+            get: {
+                tags: [
+                    name
+                ],
+                operationId: `find${name}ById`,
+                parameters: commonReadParams({
+                    base: name,
+                    ctx,
+                    refs
+                }),
+                responses: findByIdResponse,
+                security: secured
+            },
+            patch: {
+                tags: [
+                    name
+                ],
+                operationId: `update${name}ById`,
+                requestBody: requestBody(updateRef, false),
+                responses: updateResponse,
+                security: secured
+            },
+            delete: {
+                tags: [
+                    name
+                ],
+                operationId: `delete${name}ById`,
+                responses: deleteResponse,
+                security: secured
+            }
+        }
+    };
+    if (allowDuplicate) paths[`${base}/{id}/duplicate`] = {
+        parameters: [
+            {
+                name: 'id',
+                in: 'path',
+                required: true,
+                schema: {
+                    type: idType
+                }
+            }
+        ],
+        post: {
+            tags: [
+                name
+            ],
+            operationId: `duplicate${name}`,
+            responses: {
+                ...jsonOk(t('collectionDuplicated'), mutationSchema),
+                ...errorResponses(ERRORS.create, t)
+            },
+            security: secured
+        }
+    };
+    return paths;
+};
+export { buildCollectionPaths };

package/dist/spec/paths/custom.d.ts

@@ -0,0 +1,9 @@
+import type { SanitizedCollectionConfig, SanitizedConfig, SanitizedGlobalConfig } from 'payload';
+import type { PathsObject } from '@scalar/openapi-types/3.2';
+import type { BuildContext } from '../../types.js';
+export declare const buildCustomEndpointPaths: ({ config, collections, globals, ctx, }: {
+    config: SanitizedConfig;
+    collections: SanitizedCollectionConfig[];
+    globals: SanitizedGlobalConfig[];
+    ctx: BuildContext;
+}) => PathsObject;

package/dist/spec/paths/custom.js

@@ -0,0 +1,41 @@
+const getOpenapiMeta = (endpoint)=>{
+    const meta = endpoint.custom?.openapi;
+    return meta && 'object' == typeof meta ? meta : void 0;
+};
+const normalizePath = (prefix, path)=>{
+    const joined = `${prefix}${path.startsWith('/') ? path : `/${path}`}`;
+    return joined.replace(/:([A-Za-z0-9_]+)/g, '{$1}');
+};
+const collect = ({ endpoints, prefix, out })=>{
+    if (!endpoints) return;
+    for (const endpoint of endpoints){
+        const meta = getOpenapiMeta(endpoint);
+        if (!meta) continue;
+        const path = normalizePath(prefix, endpoint.path);
+        const method = endpoint.method.toLowerCase();
+        out[path] = {
+            ...out[path],
+            [method]: meta
+        };
+    }
+};
+const buildCustomEndpointPaths = ({ config, collections, globals, ctx })=>{
+    const out = {};
+    collect({
+        endpoints: config.endpoints,
+        prefix: '',
+        out
+    });
+    for (const collection of collections)collect({
+        endpoints: collection.endpoints,
+        prefix: `${ctx.apiRoute}/${collection.slug}`,
+        out
+    });
+    for (const global of globals)collect({
+        endpoints: global.endpoints,
+        prefix: `${ctx.apiRoute}/globals/${global.slug}`,
+        out
+    });
+    return out;
+};
+export { buildCustomEndpointPaths };

package/dist/spec/paths/globals.d.ts

@@ -0,0 +1,7 @@
+import type { SanitizedGlobalConfig } from 'payload';
+import type { PathsObject } from '@scalar/openapi-types/3.2';
+import type { BuildContext } from '../../types.js';
+export declare const buildGlobalPaths: ({ global, ctx, }: {
+    global: SanitizedGlobalConfig;
+    ctx: BuildContext;
+}) => PathsObject;

package/dist/spec/paths/globals.js

@@ -0,0 +1,68 @@
+import { makeT } from "../../translations/index.js";
+import { ERRORS, SECURITY_SCHEME_NAME, errorResponses, isOpenToPublic, jsonOk } from "../components.js";
+import { globalSchemaName, refTo, updateSchemaName } from "../names.js";
+import { buildParamSchemas, commonReadParams } from "../params.js";
+const buildGlobalPaths = ({ global, ctx })=>{
+    const t = makeT(ctx.i18n);
+    const name = globalSchemaName(global.slug);
+    const docRef = {
+        $ref: refTo(name)
+    };
+    const updateRef = {
+        $ref: refTo(updateSchemaName(name))
+    };
+    const secured = isOpenToPublic(global.access?.read) ? void 0 : [
+        {
+            [SECURITY_SCHEME_NAME]: []
+        }
+    ];
+    const paramSchemas = buildParamSchemas({
+        fields: global.fields,
+        ctx
+    });
+    const refs = {
+        select: true,
+        populate: Boolean(paramSchemas.populate),
+        joins: Boolean(paramSchemas.joins)
+    };
+    const okDoc = jsonOk(t('globalDoc'), docRef);
+    return {
+        [`${ctx.apiRoute}/globals/${global.slug}`]: {
+            get: {
+                tags: [
+                    name
+                ],
+                operationId: `find${name}`,
+                parameters: commonReadParams({
+                    base: name,
+                    ctx,
+                    refs
+                }),
+                responses: {
+                    ...okDoc,
+                    ...errorResponses(ERRORS.globalRead, t)
+                },
+                security: secured
+            },
+            post: {
+                tags: [
+                    name
+                ],
+                operationId: `update${name}`,
+                requestBody: {
+                    content: {
+                        'application/json': {
+                            schema: updateRef
+                        }
+                    }
+                },
+                responses: {
+                    ...okDoc,
+                    ...errorResponses(ERRORS.globalUpdate, t)
+                },
+                security: secured
+            }
+        }
+    };
+};
+export { buildGlobalPaths };

package/dist/spec/paths/jobs.d.ts

@@ -0,0 +1,7 @@
+import type { SanitizedConfig } from 'payload';
+import type { PathsObject } from '@scalar/openapi-types/3.2';
+import type { BuildContext } from '../../types.js';
+export declare const buildJobsPaths: ({ config, ctx }: {
+    config: SanitizedConfig;
+    ctx: BuildContext;
+}) => PathsObject;