OpenAPI specification

[janbuchar]

It would be nice if Payload could generate an OpenAPI specification for its REST API. This could in turn be used to generate client skeletons for the likes of mobile apps and SPAs, or as documentation for external consumers of the API.

It is already possible to generate JSON schema for the collections (those are used by the type generator script). The missing parts are (to my best understanding):

• generating OpenAPI specifications for data fetching and update endpoints for all collections and globals
• implementing a way to document custom endpoints
• writing an OpenAPI spec for the built-in endpoints (auth, version control, ...)

The second and third part seem the most difficult to me. However, even having documentation for data fetching on collections and globals would be tremendously helpful for me.

I also think I could be able to help coding the first part if that's desirable.

[jacobsfletch]

@Teyras this all sounds great, totally see the value here. Would you be willing to take this on? I'm going to add this to our roadmap as priority 3. We can help as needed here if you want to blaze the way forward. The first and third bullets seem very similar to me. And custom endpoints would have to be spec'd out by hand, so we'd likely need to expose some way of injecting this into the Payload config alongside the other specs.

[janbuchar]

Great to hear that! I'll do my best then. I think my first course of action will be exposing the parts of the code responsible for converting collection and global types to jsonschema. Then I'll try to implement an endpoint that generates documentation for the data fetching endpoints.

Regarding the custom endpoint documentation, I agree that most of it will have to be handwritten, even though we may benefit from reusing the collection jsonschema components.

[krisgrm]

Maybe if you use zod as wrapper and then zod openapi plugin we can get something nice

[janbuchar]

Thanks for the tip, but I already have a prototype that uses collection json schemas generated by payload itself. I hope it'll be ready to publish soon.

[jacobsfletch]

Related: #1921

[teunmooij]

I've build a working plugin that does this: payload-swagger.
It's currently a beta as I'm adding the final pieces, but I expect to publish a final version somewhere next week.

[janbuchar]

A week ago there was no plugin, now there are two - joys of open source development. Do you want to cooperate in any way?

[teunmooij]

I'd value any feedback or feature ideas you might have, but other than that I'm not sure there would be much to cooperate on. I'm almost done with adding the last endpoints. After that it's just monitoring the future changelogs of payload to see if I need to adjust the plugins.

[janbuchar]

Here's my plugin, I'm happy for any feedback. https://github.com/Teyras/payload-oapi