Manually patch the openapi beyond what is possible from autogeneration

[ccouzens]

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:

• The protection API OpenAPI definition for Keycloak Protection API #5
• OperationIds Add operationId to method definition #8
• Useful types for all responses Version 12 has 'object' as type, but should be array of type. #9 (anything that says it returns a Stream or Map in the HTML is generated to a very generic object)
• Response codes Tidying up the OpenAPI description #6
• Various Tidying up the OpenAPI description #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

[frankhommers]

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

[frankhommers]

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]

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.