@seshuk/payload-plugin-openapi 0.2.0 → 0.2.2

package/dist/spec/buildDocument.js

@@ -164,7 +164,8 @@ const buildDocument = async (input)=>{
                 pathBase: `${ctx.apiRoute}/globals/${global.slug}`,
                 ctx,
                 schemaBase: gbase,
-                nestedTags: options.nestedTags
+                nestedTags: options.nestedTags,
+                global: true
             }));
         }
         const filteredGlobalPaths = filterOperations({

package/dist/spec/downconvert.d.ts

@@ -1,3 +1,3 @@
 import type { Document } from '@scalar/openapi-types/3.2';
-export declare const toOpenApi30: (doc: Document) => Document;
 export declare const toOpenApi31: (doc: Document) => Document;
+export declare const toOpenApi30: (doc: Document) => Document;

package/dist/spec/downconvert.js

@@ -23,9 +23,27 @@ const downconvertTo30 = (node)=>{
     }
     if (Array.isArray(out.type)) {
         const types = out.type;
-        if (types.includes(NULL)) out.nullable = true;
+        const nullable = types.includes(NULL);
         const rest = types.filter((t)=>t !== NULL);
-        out.type = 1 === rest.length ? rest[0] : rest;
+        if (1 === rest.length) {
+            out.type = rest[0];
+            if (nullable) out.nullable = true;
+        } else if (rest.length > 1) {
+            delete out.type;
+            const union = rest.map((type)=>nullable ? {
+                    type,
+                    nullable: true
+                } : {
+                    type
+                });
+            if (out.anyOf) out.allOf = [
+                ...out.allOf ?? [],
+                {
+                    anyOf: union
+                }
+            ];
+            else out.anyOf = union;
+        }
     }
     if ('const' in out) {
         out.enum = [
@@ -39,17 +57,18 @@ const downconvertTo30 = (node)=>{
         if (examples.length > 1) out['x-examples'] = examples;
         delete out.examples;
     }
+    if (Array.isArray(out.required) && 0 === out.required.length) delete out.required;
     for (const keyword of UNSUPPORTED_KEYWORDS)delete out[keyword];
     return out;
 };
-const toOpenApi30 = (doc)=>{
-    const converted = downconvertTo30(doc);
-    converted.openapi = '3.0.4';
-    return converted;
-};
 const toOpenApi31 = (doc)=>({
         ...doc,
         openapi: '3.1.2',
-        tags: doc.tags?.map(({ kind: _kind, parent: _parent, ...rest })=>rest)
+        tags: doc.tags?.map(({ kind: _kind, parent: _parent, summary: _summary, ...rest })=>rest)
     });
+const toOpenApi30 = (doc)=>{
+    const converted = downconvertTo30(toOpenApi31(doc));
+    converted.openapi = '3.0.4';
+    return converted;
+};
 export { toOpenApi30, toOpenApi31 };

package/dist/spec/entitySchemas.js

@@ -3,7 +3,7 @@ import { getTranslation } from "@payloadcms/translations";
 import { deepMerge, isPlainObject } from "../utils.js";
 import { makeT } from "../translations/index.js";
 import { AUTH_FIELDS, flattenFields } from "./fields.js";
-import { rewriteRefs } from "./names.js";
+import { refTo, rewriteRefs, schemaName } from "./names.js";
 const READ_HIDDEN_FIELDS = new Set([
     ...AUTH_FIELDS,
     'collection'
@@ -17,8 +17,10 @@ const stripInterfaceName = (entity)=>{
     const { interfaceName: _omit, ...rest } = entity;
     return rest;
 };
-const toComponentSchema = ({ config, source, idType })=>{
-    const jsonSchema = entityToJSONSchema(config, source, new Map(), idType);
+const toComponentSchema = ({ config, source, idType, write = false })=>{
+    const jsonSchema = entityToJSONSchema(config, source, new Map(), idType, void 0, void 0, {
+        forceInlineBlocks: write
+    });
     const blockSlugs = new Set((config.blocks ?? []).map((b)=>b.slug));
     const schema = rewriteRefs(jsonSchema, blockSlugs);
     delete schema.title;
@@ -124,12 +126,33 @@ const removeProps = (schema, names)=>{
         schema.required = schema.required.filter((r)=>!drop.has(r));
     }
 };
-const buildBaseSchema = ({ entity, config, ctx })=>{
+const toIdType = (type)=>Array.isArray(type) ? type.map(toIdType) : 'number' === type ? 'integer' : type;
+const writeRelationshipsAsIds = (node, refs)=>{
+    if (Array.isArray(node)) {
+        for (const item of node)writeRelationshipsAsIds(item, refs);
+        return;
+    }
+    if (!isPlainObject(node)) return;
+    const oneOf = node.oneOf;
+    if (Array.isArray(oneOf) && 2 === oneOf.length && isRef(oneOf[1]) && refs.has(oneOf[1].$ref)) {
+        delete node.oneOf;
+        node.type = toIdType(oneOf[0].type);
+        return;
+    }
+    for (const value of Object.values(node))writeRelationshipsAsIds(value, refs);
+};
+const buildBaseSchema = ({ entity, config, ctx, write = false })=>{
+    const idType = ctx.defaultIDType;
     const schema = toComponentSchema({
         config,
         source: stripInterfaceName(entity),
-        idType: ctx.defaultIDType
+        idType,
+        write
     });
+    if (write) {
+        const refs = new Set((config.collections ?? []).map((c)=>refTo(schemaName(c.slug))));
+        writeRelationshipsAsIds(schema, refs);
+    }
     const isAuth = 'auth' in entity && Boolean(entity.auth);
     if (isAuth) removeProps(schema, READ_HIDDEN_FIELDS);
     applyFieldOverrides({
@@ -149,38 +172,24 @@ const cloneSchema = (schema)=>({
             ...schema.required
         ] : schema.required
     });
-const flattenRelationships = ({ schema, fields, idType })=>{
-    if (!schema.properties) return;
-    const idSchema = {
-        type: 'number' === idType ? 'integer' : 'string'
-    };
-    for (const field of flattenFields(fields)){
-        if ('relationship' !== field.type && 'upload' !== field.type) continue;
-        const name = 'name' in field ? field.name : void 0;
-        if (name && name in schema.properties) schema.properties[name] = 'hasMany' in field && field.hasMany ? {
-            type: 'array',
-            items: idSchema
-        } : idSchema;
-    }
-};
 const buildEntitySchemas = async ({ entity, config, ctx })=>{
     const read = buildBaseSchema({
         entity,
         config,
         ctx
     });
+    const write = buildBaseSchema({
+        entity,
+        config,
+        ctx,
+        write: true
+    });
     const isAuth = 'auth' in entity && Boolean(entity.auth);
-    const idType = ctx.defaultIDType;
-    const create = cloneSchema(read);
+    const create = cloneSchema(write);
     if (Array.isArray(create.required)) {
         const optional = new Set(SERVER_FIELDS);
         create.required = create.required.filter((r)=>!optional.has(r));
     }
-    flattenRelationships({
-        schema: create,
-        fields: entity.fields,
-        idType
-    });
     if (isAuth && create.properties) {
         create.properties.password = {
             type: 'string'
@@ -192,14 +201,9 @@ const buildEntitySchemas = async ({ entity, config, ctx })=>{
             ])
         ];
     }
-    const update = cloneSchema(read);
+    const update = cloneSchema(write);
     delete update.required;
     if (update.properties) delete update.properties.id;
-    flattenRelationships({
-        schema: update,
-        fields: entity.fields,
-        idType
-    });
     if (isAuth && update.properties) update.properties.password = {
         type: 'string'
     };

package/dist/spec/filters.js

@@ -3,7 +3,9 @@ const SYSTEM_COLLECTIONS = new Set([
     'payload-locked-documents',
     'payload-preferences',
     'payload-migrations',
-    'payload-folders'
+    'payload-folders',
+    'payload-kv',
+    'payload-query-presets'
 ]);
 const HTTP_METHODS = [
     'get',

package/dist/spec/params.d.ts

@@ -1,6 +1,6 @@
 import type { Field } from 'payload';
 import type { ParameterObject, SchemaObject } from '@scalar/openapi-types/3.2';
-import type { BuildContext } from '../types.js';
+import type { BuildContext, Entity } from '../types.js';
 export declare const buildSelectSchema: ({ fields, ctx }: {
     fields: Field[];
     ctx: BuildContext;
@@ -38,6 +38,14 @@ export declare const commonReadParams: ({ base, ctx, refs, }: {
     ctx: BuildContext;
     refs: ReadParamRefs;
 }) => ParameterObject[];
+export type WriteOperation = 'create' | 'update' | 'updateByID' | 'delete' | 'duplicate' | 'globalUpdate';
+export declare const writeParams: ({ base, entity, ctx, refs, operation, }: {
+    base: string;
+    entity: Entity;
+    ctx: BuildContext;
+    refs: ReadParamRefs;
+    operation: WriteOperation;
+}) => ParameterObject[];
 export declare const whereParam: (base: string) => ParameterObject;
 export declare const buildListParams: ({ base, fields, ctx, refs, }: {
     base: string;

package/dist/spec/params.js

@@ -300,6 +300,98 @@ const commonReadParams = ({ base, ctx, refs })=>{
     if (refs.joins) params.push(objectParam('joins', refTo(joinsSchemaName(base))));
     return params;
 };
+const SHARED = [
+    'depth',
+    'locale',
+    'fallback-locale',
+    'select',
+    'populate'
+];
+const ALL_LOCALES = [
+    'publishAllLocales',
+    'unpublishAllLocales'
+];
+const WRITE_PARAMS = {
+    create: new Set([
+        ...SHARED,
+        'draft',
+        'autosave',
+        'publishAllLocales'
+    ]),
+    update: new Set([
+        ...SHARED,
+        'draft',
+        'trash',
+        'overrideLock',
+        ...ALL_LOCALES
+    ]),
+    updateByID: new Set([
+        ...SHARED,
+        'draft',
+        'trash',
+        'autosave',
+        'overrideLock',
+        ...ALL_LOCALES
+    ]),
+    delete: new Set([
+        ...SHARED,
+        'trash',
+        'overrideLock'
+    ]),
+    duplicate: new Set([
+        ...SHARED,
+        'draft',
+        'selectedLocales[]'
+    ]),
+    globalUpdate: new Set([
+        ...SHARED,
+        'draft',
+        'autosave',
+        ...ALL_LOCALES
+    ])
+};
+const entityWriteParams = (entity, ctx)=>{
+    const t = makeT(ctx.i18n);
+    const flag = (name, key)=>({
+            name,
+            in: 'query',
+            description: t(key),
+            schema: {
+                type: 'boolean'
+            }
+        });
+    const drafts = entity.versions ? entity.versions.drafts : false;
+    const params = [];
+    if (drafts && drafts.autosave) params.push(flag('autosave', 'paramAutosave'));
+    if (drafts && drafts.localizeStatus) {
+        params.push(flag('publishAllLocales', 'paramPublishAllLocales'));
+        params.push(flag('unpublishAllLocales', 'paramUnpublishAllLocales'));
+    }
+    if (false !== entity.lockDocuments) params.push(flag('overrideLock', 'paramOverrideLock'));
+    if (ctx.locales.length > 0) params.push({
+        name: 'selectedLocales[]',
+        in: 'query',
+        description: t('paramSelectedLocales'),
+        style: 'form',
+        explode: true,
+        schema: {
+            type: 'array',
+            items: {
+                type: 'string',
+                enum: ctx.locales
+            }
+        }
+    });
+    return params;
+};
+const writeParams = ({ base, entity, ctx, refs, operation })=>[
+        ...commonReadParams({
+            base,
+            ctx,
+            refs
+        }),
+        ...entityWriteParams(entity, ctx)
+    ].filter((p)=>WRITE_PARAMS[operation].has(p.name));
 const whereParam = (base)=>objectParam('where', refTo(querySchemaName(base)));
 const buildListParams = ({ base, fields, ctx, refs })=>{
     const params = [
@@ -341,4 +433,4 @@ const buildListParams = ({ base, fields, ctx, refs })=>{
     if (collectionHasFilters(fields)) params.push(whereParam(base));
     return params;
 };
-export { buildJoinsSchema, buildListParams, buildParamSchemas, buildPopulateSchema, buildQueryOperationsSchema, buildSelectSchema, collectionHasFilters, commonReadParams, whereParam };
+export { buildJoinsSchema, buildListParams, buildParamSchemas, buildPopulateSchema, buildQueryOperationsSchema, buildSelectSchema, collectionHasFilters, commonReadParams, whereParam, writeParams };

package/dist/spec/paths/auth.js

@@ -2,40 +2,63 @@ 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 {
+const identifierBody = (auth, extra = {})=>{
+    const email = {
+        type: 'string',
+        format: 'email'
+    };
+    const username = {
+        type: 'string'
+    };
+    const extraRequired = Object.keys(extra);
+    const loginWithUsername = auth?.loginWithUsername;
+    const base = {
+        type: 'object',
+        additionalProperties: false
+    };
+    if (!loginWithUsername) return {
+        ...base,
         properties: {
-            username: {
-                type: 'string'
-            }
+            email,
+            ...extra
         },
         required: [
-            'username'
+            'email',
+            ...extraRequired
         ]
     };
-    if (loginWithUsername) return {
+    if ('object' == typeof loginWithUsername && loginWithUsername.allowEmailLogin) return {
+        ...base,
         properties: {
-            email: {
-                type: 'string',
-                format: 'email'
+            email,
+            username,
+            ...extra
+        },
+        ...extraRequired.length > 0 ? {
+            required: extraRequired
+        } : {},
+        anyOf: [
+            {
+                required: [
+                    'email'
+                ]
             },
-            username: {
-                type: 'string'
+            {
+                required: [
+                    'username'
+                ]
             }
-        },
-        required: []
+        ]
     };
     return {
+        ...base,
         properties: {
-            email: {
-                type: 'string',
-                format: 'email'
-            }
+            username,
+            ...extra
         },
         required: [
-            'email'
+            'username',
+            ...extraRequired
         ]
     };
 };
@@ -48,7 +71,6 @@ const buildAuthPaths = ({ collection, ctx, includeAdmin, nestedTags })=>{
     const tag = [
         nestedTags ? authTagName(name) : name
     ];
-    const ident = identifierProps(auth);
     const userRef = {
         $ref: refTo(name)
     };
@@ -64,20 +86,11 @@ const buildAuthPaths = ({ collection, ctx, includeAdmin, nestedTags })=>{
     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'
-                    ]
-                }),
+                requestBody: jsonBody(identifierBody(auth, {
+                    password: {
+                        type: 'string'
+                    }
+                })),
                 responses: {
                     200: jsonResponse(t('authLogin'), {
                         type: 'object',
@@ -146,19 +159,7 @@ const buildAuthPaths = ({ collection, ctx, includeAdmin, nestedTags })=>{
         },
         [`${base}/forgot-password`]: {
             post: op(`forgotPassword${name}`, ERRORS.authAction, {
-                requestBody: jsonBody({
-                    type: 'object',
-                    additionalProperties: false,
-                    properties: {
-                        email: {
-                            type: 'string',
-                            format: 'email'
-                        }
-                    },
-                    required: [
-                        'email'
-                    ]
-                }),
+                requestBody: jsonBody(identifierBody(auth)),
                 responses: messageResponse(t('authForgotPassword'))
             })
         },
@@ -247,21 +248,9 @@ const buildAuthPaths = ({ collection, ctx, includeAdmin, nestedTags })=>{
             })
         };
     }
-    if (auth.maxLoginAttempts && auth.maxLoginAttempts > 0) paths[`${base}/unlock`] = {
+    paths[`${base}/unlock`] = {
         post: op(`unlock${name}`, ERRORS.authAction, {
-            requestBody: jsonBody({
-                type: 'object',
-                additionalProperties: false,
-                properties: {
-                    email: {
-                        type: 'string',
-                        format: 'email'
-                    }
-                },
-                required: [
-                    'email'
-                ]
-            }),
+            requestBody: jsonBody(identifierBody(auth)),
             responses: messageResponse(t('authUnlock'))
         })
     };

package/dist/spec/paths/collections.js

@@ -1,7 +1,7 @@
 import { makeT } from "../../translations/index.js";
-import { ERRORS, errorResponses, jsonOk, uploadRequestBody } from "../components.js";
+import { ERRORS, errorResponses, jsonOk, jsonResponse, uploadRequestBody } from "../components.js";
 import { createSchemaName, listSchemaName, refTo, schemaName, updateSchemaName } from "../names.js";
-import { buildListParams, buildParamSchemas, commonReadParams } from "../params.js";
+import { buildListParams, buildParamSchemas, commonReadParams, writeParams } from "../params.js";
 const buildCollectionPaths = ({ collection, ctx, security = {} })=>{
     const t = makeT(ctx.i18n);
     const name = schemaName(collection.slug);
@@ -62,7 +62,7 @@ const buildCollectionPaths = ({ collection, ctx, security = {} })=>{
         ...errorResponses(ERRORS.read, t)
     };
     const createResponse = {
-        ...jsonOk(t('collectionCreated'), mutationSchema),
+        201: jsonResponse(t('collectionCreated'), mutationSchema),
         ...errorResponses(ERRORS.create, t)
     };
     const updateResponse = {
@@ -118,22 +118,36 @@ const buildCollectionPaths = ({ collection, ctx, security = {} })=>{
         }),
         ...errorResponses(ERRORS.list, t)
     };
-    const whereParameter = buildListParams({
+    const listParams = buildListParams({
         base: name,
         fields: collection.fields,
         ctx,
         refs
-    }).find((p)=>'where' === p.name);
-    const bulkParams = whereParameter ? [
-        whereParameter
-    ] : [];
+    });
+    const bulkParams = listParams.filter((p)=>'where' === p.name);
+    const bulkUpdateParams = listParams.filter((p)=>[
+            'limit',
+            'sort',
+            'where'
+        ].includes(p.name));
+    const write = (operation)=>writeParams({
+            base: name,
+            entity: collection,
+            ctx,
+            refs,
+            operation
+        });
+    const deleteParams = write('delete');
     const bulkOps = allowBulk ? {
         patch: {
             tags: [
                 name
             ],
             operationId: `update${name}`,
-            parameters: bulkParams,
+            parameters: [
+                ...bulkUpdateParams,
+                ...write('update')
+            ],
             requestBody: requestBody(updateRef, false),
             responses: bulkUpdateResponse,
             security: secUpdate
@@ -143,7 +157,10 @@ const buildCollectionPaths = ({ collection, ctx, security = {} })=>{
                 name
             ],
             operationId: `delete${name}`,
-            parameters: bulkParams,
+            parameters: [
+                ...bulkParams,
+                ...deleteParams
+            ],
             responses: bulkDeleteResponse,
             security: secDelete
         }
@@ -169,6 +186,7 @@ const buildCollectionPaths = ({ collection, ctx, security = {} })=>{
                     name
                 ],
                 operationId: `create${name}`,
+                parameters: write('create'),
                 requestBody: requestBody(createRef, fileRequiredOnCreate),
                 responses: createResponse,
                 security: secCreate
@@ -215,6 +233,7 @@ const buildCollectionPaths = ({ collection, ctx, security = {} })=>{
                     name
                 ],
                 operationId: `update${name}ById`,
+                parameters: write('updateByID'),
                 requestBody: requestBody(updateRef, false),
                 responses: updateResponse,
                 security: secUpdate
@@ -224,6 +243,7 @@ const buildCollectionPaths = ({ collection, ctx, security = {} })=>{
                     name
                 ],
                 operationId: `delete${name}ById`,
+                parameters: deleteParams,
                 responses: deleteResponse,
                 security: secDelete
             }
@@ -245,6 +265,7 @@ const buildCollectionPaths = ({ collection, ctx, security = {} })=>{
                 name
             ],
             operationId: `duplicate${name}`,
+            parameters: write('duplicate'),
             responses: {
                 ...jsonOk(t('collectionDuplicated'), mutationSchema),
                 ...errorResponses(ERRORS.create, t)

package/dist/spec/paths/globals.js

@@ -1,7 +1,7 @@
 import { makeT } from "../../translations/index.js";
 import { ERRORS, errorResponses, jsonOk } from "../components.js";
 import { globalSchemaName, refTo, updateSchemaName } from "../names.js";
-import { buildParamSchemas, commonReadParams } from "../params.js";
+import { buildParamSchemas, commonReadParams, writeParams } from "../params.js";
 const buildGlobalPaths = ({ global, ctx, security = {} })=>{
     const t = makeT(ctx.i18n);
     const name = globalSchemaName(global.slug);
@@ -21,7 +21,6 @@ const buildGlobalPaths = ({ global, ctx, security = {} })=>{
         populate: Boolean(paramSchemas.populate),
         joins: Boolean(paramSchemas.joins)
     };
-    const okDoc = jsonOk(t('globalDoc'), docRef);
     return {
         [`${ctx.apiRoute}/globals/${global.slug}`]: {
             get: {
@@ -35,7 +34,7 @@ const buildGlobalPaths = ({ global, ctx, security = {} })=>{
                     refs
                 }),
                 responses: {
-                    ...okDoc,
+                    ...jsonOk(t('globalDoc'), docRef),
                     ...errorResponses(ERRORS.globalRead, t)
                 },
                 security: secRead
@@ -45,6 +44,13 @@ const buildGlobalPaths = ({ global, ctx, security = {} })=>{
                     name
                 ],
                 operationId: `update${name}`,
+                parameters: writeParams({
+                    base: name,
+                    entity: global,
+                    ctx,
+                    refs,
+                    operation: 'globalUpdate'
+                }),
                 requestBody: {
                     content: {
                         'application/json': {
@@ -53,7 +59,15 @@ const buildGlobalPaths = ({ global, ctx, security = {} })=>{
                     }
                 },
                 responses: {
-                    ...okDoc,
+                    ...jsonOk(t('globalDoc'), {
+                        type: 'object',
+                        properties: {
+                            message: {
+                                type: 'string'
+                            },
+                            result: docRef
+                        }
+                    }),
                     ...errorResponses(ERRORS.globalUpdate, t)
                 },
                 security: secUpdate

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

@@ -9,10 +9,11 @@ export declare const versionComponentSchemas: ({ docBase, base, idType, }: {
     base: string;
     idType: IDType;
 }) => VersionSchemas;
-export declare const buildVersionPaths: ({ entity, pathBase, ctx, schemaBase, nestedTags, }: {
+export declare const buildVersionPaths: ({ entity, pathBase, ctx, schemaBase, nestedTags, global, }: {
     entity: Entity;
     pathBase: string;
     ctx: BuildContext;
     schemaBase?: string;
     nestedTags: boolean;
+    global?: boolean;
 }) => PathsObject;