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

Closed
benhaynes opened this issue Nov 28, 2018 · 19 comments
Closed

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

benhaynes opened this issue Nov 28, 2018 · 19 comments

Comments

@benhaynes
Copy link
Sponsor Member

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
Copy link

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
Copy link
Sponsor Member Author

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
Copy link
Sponsor Member Author

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
Copy link

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
Copy link
Member

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
Copy link

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
Copy link
Member

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
Copy link
Sponsor Member Author

benhaynes commented Apr 29, 2019

Interesting. Almost like an interface for creating custom endpoints.

@fl034
Copy link

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
Copy link
Sponsor Member Author

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
Copy link

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
Copy link

jhult commented Oct 7, 2019

Any news on this?

@benhaynes
Copy link
Sponsor Member Author

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

@LouizFC
Copy link

LouizFC commented Sep 21, 2020

Don't know if relevant, but the answer at OAI/OpenAPI-Specification#1706 (comment) gives an alternative to use the "content" field on the parameters.

@rijkvanzanten
Copy link
Member

rijkvanzanten commented Sep 21, 2020

@LouizFC Yeah! A bit more annoying to use though. For v9, we've made the params more flexible (by adding support for "raw json" in the query param), which in turn also means that the openapi specs are now fully possible 🙂

@LouizFC
Copy link

LouizFC commented Sep 22, 2020

@rijkvanzanten You are right. I tried parsing the parameters by extending an openapi java parser using the mentioned workaround and the parse logic got way more complex than I expected.

Good to know that v9 will make possible to the api to be expressed with openapi, that makes alot easier to implement clients for other languages without you guys needing to support everything directly (less overhead is always good). OpenAPI truly is a blessing.

@rijkvanzanten
Copy link
Member

rijkvanzanten commented Nov 18, 2020

This has been added in v9. You can download a customized OAS spec in your api from /server/specs/oas

@rijkvanzanten rijkvanzanten unpinned this issue Nov 19, 2020
@Eliophot
Copy link

Eliophot commented Mar 14, 2022

Hello, /server/specs/oas does not seem to take into account custom endpoints.
How can we ensure that they are taken into account?

@rijkvanzanten
Copy link
Member

rijkvanzanten commented Mar 15, 2022

Hello, /server/specs/oas does not seem to take into account custom endpoints.
How can we ensure that they are taken into account?

There's currently no way to have custom endpoint inject definitions into the generated specs

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

7 participants