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

[RFC] Allow different OpenAPI groups #20

Closed
nickvergessen opened this issue Oct 20, 2023 · 3 comments · Fixed by #24
Closed

[RFC] Allow different OpenAPI groups #20

nickvergessen opened this issue Oct 20, 2023 · 3 comments · Fixed by #24
Assignees
Labels
enhancement New feature or request

Comments

@nickvergessen
Copy link
Member

It would be quite handy, if multiple sets of OpenAPI could be generated, so each client/service can have their own APIs documented and accessible in the OCS API viewer.
E.g. in Talk we have multiple different API consumers and I would like to document and generate documentation for all of them in one way only:

Proposal

Similar to PHPUnits Group attribute and the already used IgnoreOpenAPI, we could also introduce an OpenAPI(scope: XYZ) attribute.
The openapi-extractor would then group the routes into different files and the ocs-api-viewer would show:

  • spreed - All controller methods without IgnoreOpenAPI or with OpenAPI or with OpenAPI(scope: default)
  • spreed-admin - All controller methods with OpenAPI(scope: admin)
  • spreed-signaling - All controller methods with OpenAPI(scope: signaling)
  • spreed-recording - All controller methods with OpenAPI(scope: recording)
  • spreed-sip - All controller methods with OpenAPI(scope: sip)

Depending on the discussion I can also imagine to look into this.

@nickvergessen nickvergessen added the enhancement New feature or request label Oct 20, 2023
@provokateurin
Copy link
Member

In general I agree with this idea. This also appeared in other apps where different consumers of the API exist. I'll think a bit about the implementation and will reply here.
One thing that just came to my mind is that we might want to use standardized groups. For example one group is always for clients, one for federated servers and so on. I don't know which groups would make sense, but those two are definitely appearing in multiple apps.

@provokateurin
Copy link
Member

If we introduce a OpenAPI attribute I would prefer to give it a parameter ignore and deprecate the IgnoreOpenAPI attribute.

@nickvergessen
Copy link
Member Author

nickvergessen commented Oct 28, 2023

PR at #24 with links to server changes, ocs api viewer and notifications app as sample

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

Successfully merging a pull request may close this issue.

2 participants