Support Payload api route config

.zed/settings.json

@@ -0,0 +1,35 @@
+{
+  "lsp": {
+    "biome": {
+      "binary": {
+        "path": "./node_modules/@biomejs/biome/bin/biome",
+        "arguments": ["lsp-proxy"]
+      }
+    }
+  },
+  "languages": {
+    "JSON": { "formatter": { "language_server": { "name": "biome" } } },
+    "JSONC": { "formatter": { "language_server": { "name": "biome" } } },
+    "JavaScript": {
+      "formatter": { "language_server": { "name": "biome" } },
+      "code_actions_on_format": {
+        "source.fixAll.biome": true,
+        "source.organizeImports.biome": true
+      }
+    },
+    "TSX": {
+      "formatter": { "language_server": { "name": "biome" } },
+      "code_actions_on_format": {
+        "source.fixAll.biome": true,
+        "source.organizeImports.biome": true
+      }
+    },
+    "TypeScript": {
+      "formatter": { "language_server": { "name": "biome" } },
+      "code_actions_on_format": {
+        "source.fixAll.biome": true,
+        "source.organizeImports.biome": true
+      }
+    }
+  }
+}

package.json

@@ -1,7 +1,7 @@
 {
   "name": "payload-oapi",
   "description": "An OpenAPI plugin for Payload CMS",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "homepage:": "https://github.com/janbuchar/payload-oapi",
   "repository:": "https://github.com/janbuchar/payload-oapi",
   "main": "dist/index.js",

src/openapi/generators.ts

@@ -389,6 +389,7 @@ const isOpenToPublic = async (checker: Access): Promise<boolean> => {
 
 const generateCollectionOperations = async (
   collection: Collection,
+  apiBasePath: string,
 ): Promise<Record<string, OpenAPIV3.PathItemObject & OpenAPIV3_1.PathItemObject>> => {
   const { slug } = collection.config
   const { singular, plural } = collectionName(collection)
@@ -400,7 +401,7 @@ const generateCollectionOperations = async (
   } satisfies OpenAPIV3_1.ResponsesObject & OpenAPIV3.ResponsesObject
 
   return {
-    [`/api/${slug}`]: {
+    [`${apiBasePath}/${slug}`]: {
       get: {
         operationId: componentName('schemas', plural, { prefix: 'list' }),
         summary: `Retrieve a list of ${plural}`,
@@ -462,7 +463,7 @@ const generateCollectionOperations = async (
         security: (await isOpenToPublic(collection.config.access.create)) ? [] : [apiKeySecurity],
       },
     },
-    [`/api/${slug}/{id}`]: {
+    [`${apiBasePath}/${slug}/{id}`]: {
       parameters: [
         ...baseQueryParams,
         {
@@ -563,13 +564,14 @@ const generateGlobalSchemas = (
 
 const generateGlobalOperations = async (
   global: SanitizedGlobalConfig,
+  apiBasePath: string,
 ): Promise<Record<string, OpenAPIV3.PathItemObject & OpenAPIV3_1.PathItemObject>> => {
   const slug = global.slug
   const singular = globalName(global)
   const tags = [singular]
 
   return {
-    [`/api/globals/${slug}`]: {
+    [`${apiBasePath}/globals/${slug}`]: {
       get: {
         summary: `Get the ${singular}`,
         tags,
@@ -652,6 +654,15 @@ const generateComponents = (
   return { schemas, requestBodies, responses }
 }
 
+/**
+ * Prefer the `apiBasePath` from plugin options (not null),
+ * otherwise use the currently configured api route from payload.
+ */
+const getApiBasePath = (
+  options: SanitizedPluginOptions,
+  req: Pick<PayloadRequest, 'payload'>,
+): string => (options.apiBasePath !== null ? options.apiBasePath : req.payload.config.routes.api)
+
 export const generateV30Spec = async (
   req: Pick<PayloadRequest, 'payload' | 'protocol' | 'headers'>,
   options: SanitizedPluginOptions,
@@ -663,15 +674,18 @@ export const generateV30Spec = async (
     shouldIncludeCollection(collection, filters),
   )
   const globals = req.payload.globals.config.filter(global => shouldIncludeGlobal(global, filters))
+  const apiBasePath = getApiBasePath(options, req)
 
   const spec = {
     openapi: '3.0.3',
     info: options.metadata,
     servers: [{ url: `${req.protocol}//${req.headers.get('host')}` }],
     paths: Object.assign(
       {},
-      ...(await Promise.all(collections.map(generateCollectionOperations))),
-      ...(await Promise.all(globals.map(generateGlobalOperations))),
+      ...(await Promise.all(
+        collections.map(collection => generateCollectionOperations(collection, apiBasePath)),
+      )),
+      ...(await Promise.all(globals.map(global => generateGlobalOperations(global, apiBasePath)))),
     ),
     components: {
       securitySchemes: generateSecuritySchemes(options.authEndpoint),
@@ -727,15 +741,18 @@ export const generateV31Spec = async (
     shouldIncludeCollection(collection, filters),
   )
   const globals = req.payload.globals.config.filter(global => shouldIncludeGlobal(global, filters))
+  const apiBasePath = getApiBasePath(options, req)
 
   const spec = {
     openapi: '3.1.0',
     info: options.metadata,
     servers: [{ url: `${req.protocol}//${req.headers.get('host')}` }],
     paths: Object.assign(
       {},
-      ...(await Promise.all(collections.map(generateCollectionOperations))),
-      ...(await Promise.all(globals.map(generateGlobalOperations))),
+      ...(await Promise.all(
+        collections.map(collection => generateCollectionOperations(collection, apiBasePath)),
+      )),
+      ...(await Promise.all(globals.map(global => generateGlobalOperations(global, apiBasePath)))),
     ),
     components: {
       securitySchemes: generateSecuritySchemes(options.authEndpoint),

src/openapiPlugin.ts

@@ -10,6 +10,7 @@ const openapi =
     metadata,
     enabled = true,
     filters = {},
+    apiBasePath = null,
   }: PluginOptions): Plugin =>
   ({ endpoints = [], ...config }) => {
     if (!enabled) {
@@ -28,6 +29,7 @@ const openapi =
             metadata,
             authEndpoint,
             filters,
+            apiBasePath,
           }),
         },
         {

src/types.ts

@@ -21,6 +21,7 @@ export interface PluginOptions {
   authEndpoint?: string
   metadata: OpenAPIMetadata
   filters?: FilterOptions
+  apiBasePath?: string | null
 }
 
 export type SanitizedPluginOptions = Required<Omit<PluginOptions, 'enabled' | 'specEndpoint'>>

test/openapi-generators.test.ts

@@ -64,6 +64,7 @@ describe('openapi generators', () => {
         authEndpoint: '/api/auth',
         metadata: { title: 'Test API', version: '1.0' },
         filters: {},
+        apiBasePath: null,
       },
     )
 
@@ -95,6 +96,7 @@ describe('openapi generators', () => {
         authEndpoint: '/api/auth',
         metadata: { title: 'Test API', version: '1.0' },
         filters: {},
+        apiBasePath: null,
       },
     )
 
@@ -145,6 +147,7 @@ describe('openapi generators', () => {
         authEndpoint: '/api/auth',
         metadata: { title: 'Test API', version: '1.0' },
         filters: {},
+        apiBasePath: null,
       },
     )
 
@@ -179,6 +182,7 @@ describe('openapi generators', () => {
         authEndpoint: '/api/auth',
         metadata: { title: 'Test API', version: '1.0' },
         filters: {},
+        apiBasePath: null,
       },
     )
 
@@ -207,6 +211,7 @@ describe('openapi generators', () => {
         authEndpoint: '/api/auth',
         metadata: { title: 'Test API', version: '1.0' },
         filters: {},
+        apiBasePath: null,
       },
     )
 
@@ -230,6 +235,7 @@ describe('openapi generators', () => {
           authEndpoint: '/api/auth',
           metadata: { title: 'Test API', version: '1.0' },
           filters: { includeCollections: ['posts'] },
+          apiBasePath: null,
         },
       )
 
@@ -249,6 +255,7 @@ describe('openapi generators', () => {
           authEndpoint: '/api/auth',
           metadata: { title: 'Test API', version: '1.0' },
           filters: { excludeCollections: ['users'] },
+          apiBasePath: null,
         },
       )
 
@@ -268,6 +275,7 @@ describe('openapi generators', () => {
           authEndpoint: '/api/auth',
           metadata: { title: 'Test API', version: '1.0' },
           filters: { hideInternalCollections: true },
+          apiBasePath: null,
         },
       )
 
@@ -289,6 +297,7 @@ describe('openapi generators', () => {
           authEndpoint: '/api/auth',
           metadata: { title: 'Test API', version: '1.0' },
           filters: { includeCollections: [] },
+          apiBasePath: null,
         },
       )
 
@@ -317,6 +326,7 @@ describe('openapi generators', () => {
           authEndpoint: '/api/auth',
           metadata: { title: 'Test API', version: '1.0' },
           filters: { includeGlobals: ['settings'] },
+          apiBasePath: null,
         },
       )
 
@@ -344,11 +354,59 @@ describe('openapi generators', () => {
           authEndpoint: '/api/auth',
           metadata: { title: 'Test API', version: '1.0' },
           filters: { excludeGlobals: ['footer'] },
+          apiBasePath: null,
         },
       )
 
       expect(spec.paths['/api/globals/settings']).toBeDefined()
       expect(spec.paths['/api/globals/footer']).toBeUndefined()
     })
   })
+
+  test('apiBasePath option changes operation paths', async () => {
+    const payload = await buildPayload({
+      collections: [Posts],
+    })
+
+    const spec = await generateV30Spec(
+      { protocol: 'https', headers: new Headers({ host: 'localhost' }), payload },
+      {
+        openapiVersion: '3.0',
+        authEndpoint: '/api/auth',
+        metadata: { title: 'Test API', version: '1.0' },
+        filters: { hideInternalCollections: true },
+        apiBasePath: '/api/custom',
+      },
+    )
+
+    expect(spec.paths['/api/custom/posts']).toBeDefined()
+    expect(spec.paths['/api/custom/payload-preferences']).toBeUndefined()
+    expect(spec.paths['/api/custom/payload-migrations']).toBeUndefined()
+    expect(spec.paths['/api/custom/payload-locked-documents']).toBeUndefined()
+  })
+
+  test('payload routes api config changes operation paths', async () => {
+    const payload = await buildPayload({
+      collections: [Posts],
+      routes: {
+        api: '/api/custom',
+      },
+    })
+
+    const spec = await generateV30Spec(
+      { protocol: 'https', headers: new Headers({ host: 'localhost' }), payload },
+      {
+        openapiVersion: '3.0',
+        authEndpoint: '/api/auth',
+        metadata: { title: 'Test API', version: '1.0' },
+        filters: { hideInternalCollections: true },
+        apiBasePath: null,
+      },
+    )
+
+    expect(spec.paths['/api/custom/posts']).toBeDefined()
+    expect(spec.paths['/api/custom/payload-preferences']).toBeUndefined()
+    expect(spec.paths['/api/custom/payload-migrations']).toBeUndefined()
+    expect(spec.paths['/api/custom/payload-locked-documents']).toBeUndefined()
+  })
 })