ccouzens / ccouzens/keycloak-openapi
Manually patch the openapi beyond what is possible from autogeneration
- Dominant language
- Rust
- Stars
- 181
- Forks
- 65
- PR merge metrics
- No merged PRs in 30d
Description
The OpenAPI files are all currently auto-generated.
For example, for version 12.0, we download the [HTML documentation](https://www.keycloak.org/docs-api/12.0/rest-api/index.html), it gets processed and we output [OpenAPI documentation](https://github.com/ccouzens/keycloak-openapi/blob/master/keycloak/12.0.json).
This is great, as it allows me to support a large API and new versions of it without much ongoing effort. And I trust my laptop not to generate typos or make other human mistakes.
The problem is, it can only ever be as good as the HTML documentation. When the HTML documentation is missing information, my program cannot fill in the blanks.
There are several things the HTML documentation is missing:
* The protection API https://github.com/ccouzens/keycloak-openapi/issues/5
* OperationIds https://github.com/ccouzens/keycloak-openapi/issues/8
* Useful types for all responses https://github.com/ccouzens/keycloak-openapi/issues/9 (anything that says it returns a `Stream` or `Map` in the HTML is generated to a very generic object)
* Response codes https://github.com/ccouzens/keycloak-openapi/issues/6
* Various https://github.com/ccouzens/keycloak-openapi/issues/6
If someone has the time and ability, I would like them to make any of the above changes (even if incomplete) to a copy of the OpenAPI definitions in this repository.
I imagine they would be given a name like `keycloak/12.0-patched.json`.
If possible, please keep the formatting and order the same to make it easier to diff with the original versions.
Thanks in advance!
Chris
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with keycloak/12.0.json and compare it with the linked Keycloak HTML documentation. Review the related issues for the protection API, operationIds, response types, and response codes, then choose one missing area to patch in a copy such as keycloak/12.0-patched.json. Done means the selected omission is represented while preserving the original formatting and order where possible.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi
- Domain
- api
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100