Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

OpenAPI 3.0 Spec — Generate Directus API Clients (SDKs) #2255

Open
benhaynes opened this issue Nov 28, 2018 · 13 comments
Open

OpenAPI 3.0 Spec — Generate Directus API Clients (SDKs) #2255

benhaynes opened this issue Nov 28, 2018 · 13 comments

Comments

@benhaynes
Copy link
Member

@benhaynes benhaynes commented Nov 28, 2018

We already have most of our Directus API 2.x endpoints/params within Paw for testing. We could finish adding all of these and then potentially use their code generators to create SDKs for our secondary languages.

https://paw.cloud/docs/extensions/create-code-generator

We also have a Swagger file for 98% of API 1.1 — so we could update that (and make sure that OpenAPI allows for our filtering syntax now).

https://app.swaggerhub.com/apis/directus/directus/1.1#/

I'd love to get some thoughts from the community (and Core team) on this so we can finally get some momentum and wrap this up!

@ybelenko

This comment has been minimized.

Copy link

@ybelenko ybelenko commented Jan 15, 2019

Quote of @wing328:

Myself and 40+ top contributors have decided to fork Swagger Codegen so as to maintain a community-driven version called OpenAPI Generator with a better governance structure to move the project forward. Now there are 10+ core team members and contributors with proper rights to merge PRs so I think we've better PR management in OpenAPI Generator. Please refer to the Q&A for the reasons behind the fork.

Right now openapi-generator is in 4.0.0-beta version. That version contains a lot of new features, codegens and even more important breaking changes.

I've created MySQL schema generator and I'm responsible for most of PHP Slim generator updates.

You can check difference of Slim generator output:
https://github.com/OpenAPITools/openapi-generator/tree/master/samples/server/petstore/php-slim
https://github.com/swagger-api/swagger-codegen/tree/master/samples/server/petstore/slim

Quote of @wing328 again:

It's perfect time to try Openapi Generator and give us feedback so that the project team can incorporate your feedback into the 4.0.0 stable release.

@benhaynes

This comment has been minimized.

Copy link
Member Author

@benhaynes benhaynes commented Jan 18, 2019

Hey @ybelenko — we have been struggling with OpenAPI/Swagger for a while, specifically with nested deepObjects used within our filtering parameters.

GET /items/users?filter[category][eq]=vip

We would love to find an alternative that supports this syntax — do you know if OpenAPI Generator does?

Ref: https://docs.directus.io/api/reference.html#filtering

@benhaynes

This comment has been minimized.

Copy link
Member Author

@benhaynes benhaynes commented Jan 18, 2019

Looking for a Directus API Client?

Please consider 👍 this issue: OAI/OpenAPI-Specification#1706

As soon as that ticket is resolved then we can generate Directus SDKs in all the popular languages!

@benhaynes benhaynes changed the title Look into Paw/Swagger to Generate SDKs OpenAPI 3.0 Spec — Generate All Directus API Clients (SDKs) Jan 18, 2019
@benhaynes benhaynes changed the title OpenAPI 3.0 Spec — Generate All Directus API Clients (SDKs) OpenAPI 3.0 Spec — Generate Directus API Clients (SDKs) Jan 18, 2019
@fl034

This comment has been minimized.

Copy link

@fl034 fl034 commented Apr 29, 2019

Hey guys, I've been testing other headless CMSs that support automatic OpenAPI documentation. Those I've found are lacking other features that Directus supports.

So why wait until OAS is fully supporting nested filtering?
Why don't we start with a subset of features (and maybe mark the OpenAPI documentation as beta)?

Another useful idea would be to use Directus bookmarks and make API routes out of them, also documented via OAS.
With that we could setup some static filters that our mobile app needs for some use cases without writing code.

How do you think about that @benhaynes ?

@rijkvanzanten

This comment has been minimized.

Copy link
Member

@rijkvanzanten rijkvanzanten commented Apr 29, 2019

Another useful idea would be to use Directus bookmarks and make API routes out of them, also documented via OAS.

Could you expand on this? I'm not really following what you mean

@fl034

This comment has been minimized.

Copy link

@fl034 fl034 commented Apr 29, 2019

Maybe an example helps:
Let's assume I want to develop an App natively for Android and iOS.
Via Directus I want to manage data that is being displayed. Let's say podcast items and podcast series, to group multiple items.

In the app I want to display the podcast series, but only the ones that have one or more items in it.
My idea is to be able to create a bookmark (e.g. seriesFilteredForApp) that is filtered like this and make it manageable via API and documented via OAS.

In my mobile apps I could simply generate the networking client via the OpenAPI generator and be able to access this endpoint.

With this approach we would achieve some kind of static filtering, which could be useful for basic things like my example.

@rijkvanzanten

This comment has been minimized.

Copy link
Member

@rijkvanzanten rijkvanzanten commented Apr 29, 2019

Ohh, so you'd use the bookmark as a "shortcut" endpoint in a way? Eg /items/podcast?bookmark=15 or /bookmarks/15 would return all the items that match the filters / options in that bookmark?

@benhaynes

This comment has been minimized.

Copy link
Member Author

@benhaynes benhaynes commented Apr 29, 2019

Interesting. Almost like an interface for creating custom endpoints.

@fl034

This comment has been minimized.

Copy link

@fl034 fl034 commented Apr 30, 2019

Exactly. Should I file an extra feature-request issue for that :)?
And what do you guys think about offering a "beta" OAS generation?

@benhaynes

This comment has been minimized.

Copy link
Member Author

@benhaynes benhaynes commented Apr 30, 2019

You could add that as an API feature request! See what the community thinks...

We have a spec from our old API (1.1) but can't spend the time to update this since we have no reassurance that OAS will support our filter syntax. If it were a lesser feature, maybe... but filtering is a huge part of the platform.

If you would like to take a shot updating the spec, we can offer guidance!

https://app.swaggerhub.com/apis/directus/directus/1.1

@fl034

This comment has been minimized.

Copy link

@fl034 fl034 commented May 3, 2019

I created a feature request for the bookmarks idea.
And maybe I get to look into the OAS stuff, but can't make any promises yet.

@jhult

This comment has been minimized.

Copy link

@jhult jhult commented Oct 7, 2019

Any news on this?

@benhaynes

This comment has been minimized.

Copy link
Member Author

@benhaynes benhaynes commented Oct 8, 2019

This is out of our hands... we (and many other people) are waiting on this issue to get resolved:

OAI/OpenAPI-Specification#1706

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
5 participants
You can’t perform that action at this time.