feat: Add custom endpoints #53
Conversation
|
Hi, I think #47 is about injecting arbitrary paths into the openapi output. This PR is about the custom endpoints feature of Payload: https://payloadcms.com/docs/rest-api/overview#custom-endpoints The ones that are added directly to a collection's config. |
maevic
force-pushed
the
add-custom-endpoints
branch
from
e3ffca3 to
add12a0
Compare
janbuchar
left a comment
janbuchar
left a comment
There was a problem hiding this comment.
Looks solid at first glance, some tests would be much appreciated
dev/collections/Pets.ts
Outdated
| }, | ||
| }, | ||
| }, | ||
| } as CustomEndpointDocumentation<'3.1'>, |
There was a problem hiding this comment.
It doesn't feel right to require users to make a cast for type safety - perhaps a utility function would provide better DX?
There was a problem hiding this comment.
Great idea. I will implement it later
There was a problem hiding this comment.
Okay, I added a utility function to avoid the type cast. Let me know if you had something different in mind
| required: ['name'], | ||
| }, | ||
| responses: { | ||
| 200: { |
There was a problem hiding this comment.
It would be great if the user could reference the various generated OpenAPI schemas here. Will a simple $ref work here? Can you add a test that verifies that please?
There was a problem hiding this comment.
I'm not sure if I understand you correctly. The generated OpenAPI schemas aren't yet available here, as this definition will be used to generate them.
There was a problem hiding this comment.
If you know the correct component name, you can write a ref inside your custom endpoint definition - $ref: "#/components/schemas/UserResponse" or something like that. My question is if this will work as expected
There was a problem hiding this comment.
Thanks for the clarification 👍 That should be possible. I'll add a test for it
src/types.ts
Outdated
| ? OpenAPIV3_1.SchemaObject | ||
| : OpenAPIV3.SchemaObject | ||
|
|
||
| export interface CustomEndpointDocumentation<TVersion extends OpenAPIVersion = '3.1'> { |
There was a problem hiding this comment.
I'm a bit lost here. Does this still support both 3.0 and 3.1? Maybe we should enforce 3.1 syntax and convert it if the plugin is configured for 3.0?
There was a problem hiding this comment.
This is just a type generic for the user to specify what OpenAPI version he's using. If he omits this, 3.1 is used (for the types), but he has the possibility to specify 3.0 as well. The same way he needs to specify the version in the plugin config. Although I just noticed that 3.0 is the default there.
So yes, it still supports both 3.0 and 3.1. I would change it to default to 3.0, so that it's in sync with the default config version.
The plugin configuration uses 3.0 as the default version, so let's stick with that.
2 participants
This PR adds custom endpoints to the schema, if the custom endpoint contains a
custom.openapiproperty. It exports a new type for the user to help with writing the schema.