ccouzens / ccouzens/keycloak-openapi

Manually patch the openapi beyond what is possible from autogeneration

Open
#10 3 comments 0 reactions 0 assignees View on GitHub
help wanted
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.