Replies: 9 comments 5 replies
-
|
@tnorimat Hi Takashi, long time ago, we had a discussion about this and the initial idea was to create the Open API descriptors first and generate our HTML documentation, and the API code. It's been a while since it was created, and I believe it's a good idea to revisit and check if we have a better approach. I think it's a good idea, and I would love to hear more about what you have in mind. |
Beta Was this translation helpful? Give feedback.
-
|
Hello @abstractj , there is the similar discussion. In this discussion, generating OpenAPI documentation from codes automatically (ex. by using some annotations) has been suggested. The advantage of this way is to generate OpenAPI documentation automatically so that this documentation comply with actual codes completely. Also this way can remove costs for maintaining OpenAPI documentation that may arise if we make these documentation manually. IMO, this way is reasonable, but I've not yet found how to realize this way. I've now investigating Smallrye OpenAPI extension. |
Beta Was this translation helpful? Give feedback.
-
|
I think this is an anti-pattern. It basically says "the code is not written against the specification; the specification is inferred from the code". The consequences are immediately obvious: since the code is the source of truth, there is no way to actually detect breaking changes since, with this pattern, tests are written in order to satisfy the code, instead of being written to satisfy some expectations - the specification. You will end up making some changes to the code, which will in turn change the specification, letting us all at the mercy of a breaking change in the specification that nobody is able to detect. |
Beta Was this translation helpful? Give feedback.
-
|
@tnorimat let's move the conversation to #8899, so we have things in a single place. |
Beta Was this translation helpful? Give feedback.
-
|
Hello I am trying to add a new attribute to a user profile of a certain realm, for this I am using the following request: And this operation is returning me 405 Method not allowed what can I be doing wrong? |
Beta Was this translation helpful? Give feedback.
-
|
This looks correct, except that you wrote And that the body is incorrect, because the UPConfig attributes should be directly set at root level, there is no intermediate "UPConfig" element. But that should not lead to the 405 error. Maybe you can try whether the corresponding GET endpoint works? |
Beta Was this translation helpful? Give feedback.
-
|
Hi there, When generating some code from the OpenAPI spec, I get the following: The same errors are displayed in OpenAPI specifications validation tools like https://editor.swagger.io/ I can work around that by disabling the spec validation when generating the client code, and as the two Representations above are not used on the endpoints I call, I have no error at runtime. So I have two questions:
|
Beta Was this translation helpful? Give feedback.
-
|
Hi, Would it be possible to add operationId field to all operations? This can dramatically improve the quality of the generated code by tools like nswag. Cheers |
Beta Was this translation helpful? Give feedback.
-
|
Hi, I've added the operationId field to all operations — that should definitely help with tools like NSwag or OpenApi Generator. You can check out the changes here: #39011. Cheers, |
Beta Was this translation helpful? Give feedback.
-
|
That's really great! Thnx! |
Beta Was this translation helpful? Give feedback.
-
|
And where can I mention any issues I encounter using the openapi document? For instance adding a user returns a 201 status, but the openapi document describes 200. |
Beta Was this translation helpful? Give feedback.
-
|
I didn't catch the info about headers in OpenAPI documents. Is there possibility to add the header's info in the .yml and . json files? |
Beta Was this translation helpful? Give feedback.
-
|
Is it possible to define optional parameters in the OpenAPI specification? Currently, when generating a C# client, many parameters are required by default, which can be cumbersome when only a subset is needed. For example, retrieving user information by In addition, are the OpenAPI definitions available at https://www.keycloak.org/docs-api/latest/rest-api/index.html still in Preview status? When is an official version of these definitions expected to be released? |
Beta Was this translation helpful? Give feedback.
-
|
You got it backwards. Parameters are by default optional unless marked required which for the endpoint you are showing only realm is required. Whatever tooling you are using to generate the client is not spec compliant or you are misreading the C# method signature. We are currently using Kiota and it manages to generate that endpoint so that only realm is required. Also I'm not completely firm on my memory but before, when we used the official openapi generator, it also properly generated the calls without requiring all these optional parameters. |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
-
This topic has already been treated by KEYCLOAK-6662.
The aim of this discussion is to document Admin REST API in OpenAPI.
Its motivation is that it makes easy for keycloak administrator to test and manage their keycloak.
As for Account REST API, there are some JIRA ticket(KEYCLOAK-9655, KEYCLOAK-14744) and corresponding project(keycloak-rest-api-description)).
To follow this project, Admin REST APIs are also documented by OpenAPI.
I'm not sure adding Admin REST APIs' documentation is added to existing project, or create its new project.
What do you think about this idea? I am willing to work on it if this idea can is accepted by keycloak community.
Beta Was this translation helpful? Give feedback.
All reactions