Proposal: Expose OpenAPI / Swagger specification

[MarvinJWendt]

Hi, I really love this project! One feature I am missing is an exposed OpenAPI / Swagger specification file. In this proposal I will address the benefits that an implementation would bring.

Before I start:
I know that this issue was posted before (#209, #414. #799), but I've not seen those issues to really state what the benefits to the users would be (IMO there are a lot more benefits than just the documentation and client generation).

Benefits of exposing an OpenAPI / Swagger specification

OpenAPI specifications are modeled around the Database model, and thus they are type-aware. Through various generators (like https://github.com/OpenAPITools/openapi-generator), the user can generate a client library for the most common programming languages from an OpenAPI specification file. This generated library would take into account, what type the data has. The IDE would then also display the model of the data in the autocomplete.

Assumed this is the model in the database:

Database
└── Collections
    ├── Users
    ├── Books
    │   ├── id: number
    │   ├── author: string
    │   └── price: number
    └── Movies
        ├── id: number
        ├── studio: string
        └── price: number

This is how calls to data could look like, in a go client example:
(using an autogenerated API from an OpenAPI spec I wrote)

book, _, err := api.BooksApi.BooksCreate(context.Background()).BooksRequest(swagger.BooksRequest{
		Id: swagger.PtrInt32(1337),
		Author:  swagger.PtrString("SomeAuthor"),
		Price: swagger.PtrInt32(10_00),
}).Execute()

bookCount, _ , _ := api.BooksApi.BooksCount(context.Background()).Execute()

/// ...

Use case

The use case of this would primarily be when users don't have a pocketbase SDK for their current project language (Java / Kotlin for native Android development, Objective-C / Swift for native iOS development, Go client, etc...). But it can also be used if the database model is huge, and the developers want to have a model-aware autocomplete.

Another use case would be, that the OpenAPI spec can be imported in tools like Postman, to test and experiment with the API. It is also possible, and a common scenario, to create API tests in Postman, Hoppscotch (etc.) and use them for unit tests in production / enterprise grade applications.

// EDIT (to put my comment into the proposal):
Another thing that I just noticed is that frontend devs would not need an admin account to see the database model when a spec file is exposed. In many cases, this could be an important point for bigger teams.

Final statement

I think adding an autogenerated OpenAPI specification endpoint would just bring advantages to the users. It does not have to be used, but the possibilities that OpenAPI brings are huge (CI integration, unit tests, reliability checks, postman integration, autocomplete in libraries, etc.)

I understand that the implementation would need some effort, but once it's done, I don't think it needs to be updated often.

[MarvinJWendt]

Just something I found, but I never used it: https://github.com/swaggo/echo-swagger

This library claims to automatically generate a Swagger specification for the echo framework. Maybe this could help to implement this feature :)

[MoritzHeld]

I really like this idea 👍
We could make use of that too in our current project, especially the autocomplete feature would help our frontend devs.
Thanks in advance for your time.

[MarvinJWendt]

especially the autocomplete feature would help our frontend devs

Another thing that I just noticed is that frontend devs would not need an admin account to see the database model when a spec file is exposed. In many cases, this could be an important point for bigger teams.

[ganigeorgiev]

Personally I don't find the generated swagger client very useful, but since this seems to be a common request, I have added it to the roadmap. For now it is prioritized somewhere after the planned migration improvements and filters enhancements (IN operator(s) and multi-rels match support).

My main concern is the maintenance cost that may come with this but maybe @MarvinJWendt is right and it will not be too hard to keep it up-to-date with future changes.

[mbnoimi]

+1

[onurbamaro]

+1

Thank you for this great project, btw!

[pr0ton11]

+1

[drewlustro]

I'm interested in this too! I'm trying to scaffold a pocketbase schema from one specified in OpenAPI / Swagger.

Until it or something adjacent is supported (like JSON Schema), my options are:

• manually mirror the schema in admin UI – lots of time + clicking, error-prone
• learn Go, study Pocketbase's source to manually work with SQLite – very time-consuming, brittle, API will likely change, such as reserved attributes on table fields
• write a transformer that converts OpenAPI / Swagger to the experimental API within pb_migrations/ – time-consuming, brittle, API will likely change

@ganigeorgiev – in addition to client/server type safety, supporting OpenAPI would allow one to bootstrap their pocketbase DB schema rapidly. Please consider it!

+1 great project 🙏

[Mizaro]

I see that the in the Admin Dashboard, there is a button "API Preview" that has all the information that is required to create an OpenAPI file. Do you think it can be reused?

[pr0ton11]

Ok I am trying to do an approach with Swagger 2.0, because there is a plugin for the primary used echo server. I'll let you know when I'll open a PR by referencing this issue.

[SasukeK93]

@ganigeorgiev Any updates about this ?

[ganigeorgiev]

Nothing has changed and for now this still remains a low priority.

You can check the current tasks priorities in https://github.com/orgs/pocketbase/projects/2/views/1.

[MarArMar]

CI integration AND types generation is a huge Use Case for Medium Size companies & Enterprise grade applications

Had the case this morning where my local environment and prod DB did not have the same schema, could have been detected automatically and stop a build for example

[xxyuze]

+1

[pr0ton11]

This is actually pretty difficult to do because the fields for the API are designed within the UI and can be updated which makes static generation impossible.
It would require some sort of middleware that queries the current endpoints, entities and maps them to the openAPI spec.

[MarvinJWendt]

This is actually pretty difficult to do because the fields for the API are designed within the UI and can be updated which makes static generation impossible. It would require some sort of middleware that queries the current endpoints, entities and maps them to the openAPI spec.

It could be statically generated every time the fields are modified. Just like migrations are generated the same way (if enabled).

[matesolutions]

+1

[EwenQuim]

Working on Fuego (a Go framework that generates OpenAPI spec from source code), I've gained a lot of experience in dynamic OpenAPI generation (at start time), it might be a solution.

I'll try to do what I can here in the next weeks :)

Thank you @ganigeorgiev for this software, it's wonderful!

[ganigeorgiev]

@EwenQuim keep in mind that for now #4355 remains with highest priority and even if someone opens a PR for this I make no promise that I'll have the time to review it and merge it (see also the Contributing note).

Also note that this particular feature doesn't necessary need to be part of the repo and can be implemented as separate server-side "plugin"/library similar to the ones in the plugins dir.