search

ccouzens / keycloak-openapi

OpenAPI definitions for Keycloak's Admin API
168 stars 66 forks source link

Manually patch the openapi beyond what is possible from autogeneration #10

Open ccouzens opened 3 years ago

ccouzens commented 3 years ago

The OpenAPI files are all currently auto-generated.

For example, for version 12.0, we download the HTML documentation, it gets processed and we output OpenAPI documentation.

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:

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

frankhommers commented 3 years ago

Yes I have done this by hand. For a lot. But not for "Response" and "Map".

frankhommers commented 3 years ago

Just got an idea: but I am not sure if this is usable: Could you make your generator so that it falls back to an older version to get the datatype? That would save a lot of work!

ccouzens commented 3 years ago

Just got an idea: but I am not sure if this is usable: Could you make your generator so that it falls back to an older version to get the datatype? That would save a lot of work!

I have been thinking of a similiar idea.

When /route/{id} exists, and returns X, then the generator might be able to assume that /route/ returns an array of X.

Unfortunately, I have recently started a volunteer role in addition to my normal job- so I won't have the free time to make the change until maybe the summer.