Thanks, @DAHAG-ArisNourbakhsh, for your pull request. I think the changes you suggested have been replaced by the ones in #20669 by @jsorah.

Could you point me to the url on the keycloak documentation page where either the raw open-api json/yml can be found at? I thought the PR you linked only generated the documentation html.

@abstractj - looks like this PR is taking the intermediate OpenAPI spec generated from the changes I made and making it available from the rest-api documentation page, so I would consider this additive to what I did previously. This seems like a middle ground between not giving devs an easily accessible OpenAPI spec and publishing it on a running KC instance, and instead, just publishing the API spec on the rest-api documentation page for a particular KC release.

Unreported flaky test detected

If the below flaky tests below are affected by the changes, please review and update the changes accordingly. Otherwise, a maintainer should report the flaky tests prior to merging the PR.

org.keycloak.testsuite.ui.account2.WelcomeScreenTest#accountSecurityTest

Keycloak CI - Account Console IT (firefox)

org.awaitility.core.ConditionTimeoutException: Assertion condition defined as a org.keycloak.testsuite.util.URLAssert URL expected to begin with: https://localhost:8543/auth/realms/test/protocol/openid-connect/auth ; actual URL: https://localhost:8543/auth/realms/test/account/#/security/device-activity within 10 seconds.
	at org.awaitility.core.ConditionAwaiter.await(ConditionAwaiter.java:167)
	at org.awaitility.core.AssertionCondition.await(AssertionCondition.java:119)
	at org.awaitility.core.AssertionCondition.await(AssertionCondition.java:31)
	at org.awaitility.core.ConditionFactory.until(ConditionFactory.java:985)
...

Report flaky test

org.keycloak.testsuite.model.ConcurrentHashMapStorageTest#testStorageSeparation

Keycloak CI - Store Model Tests

org.keycloak.models.locking.LockAcquiringTimeoutException: Lock [org.keycloak.models.RealmModel] already acquired by keycloak instance [null] at the time [null]
	at org.keycloak.models.map.lock.MapGlobalLockProvider.withLock(MapGlobalLockProvider.java:94)
	at org.keycloak.models.locking.GlobalLockProvider.withLock(GlobalLockProvider.java:45)
	at org.keycloak.models.map.storage.jpa.JpaMapStorageProviderFactory.update(JpaMapStorageProviderFactory.java:559)
	at org.keycloak.models.map.storage.jpa.JpaMapStorageProviderFactory.validateAndUpdateSchema(JpaMapStorageProviderFactory.java:481)
...

Report flaky test

What would be the way to generate the openapi.json with the proposed changes? I cant seem to find it anywhere after running mvnw clean install -Pdistribution.

What would be the way to generate the openapi.json with the proposed changes? I cant seem to find it anywhere after running mvnw clean install -Pdistribution.

They were already generated even without this PR. This just copies them so the exported documentation also contains them

From a blank checkout of keycloak:

mvnw -pl quarkus/deployment,quarkus/dist -am -DskipTests clean install
cd services
mvn -s ../maven-settings.xml -Pjboss-release clean package

and then they can be found under \services\target\apidocs-rest\output

@abstractj @jsorah @DAHAG-ArisNourbakhsh
Are there any tasks to proceed with this PR to merge? Just rebasing?

@abstractj @jsorah @DAHAG-ArisNourbakhsh Are there any tasks to proceed with this PR to merge? Just rebasing?

As far as I'm concerned, only rebasing.

I had a look, and I see at least two levels of problems:

• Typo in the docs where it should be OpenAPI
• Using the passthrough syntax where it should use AsciiDoc

A more general question:

• Is the OpenAPI specification a fully supported feature that everyone should use, or is it rather a preview feature? I think I still see a lot of warnings when it is generated.

Looping in @999eagle as I know you have been working with the OpenAPI specs. I'd be happy if you could comment on how usable the currently generated OpenAPI documentation is.

Using the passthrough syntax where it should use AsciiDoc

The passthrough syntax was the only way I understood on how to get the html anchor tags into the final document.

Is the OpenAPI specification a fully supported feature that everyone should use, or is it rather a preview feature? I think I still see a lot of warnings when it is generated.

My opinion on this:

There are most likely still a lot of problems with the OpenAPI definition that go beyond warnings that can only be found when using it in real world scenarios. For example wrong status codes that the static validation can't pickup (dahag-ag/keycloak-openapi#8) (POST /admin/realms to be precise. Should be a 201/20X but says it's a 200)

This status code is also completely wrong in the html APIDocs as they are based on the faulty OpenAPI specs. So I'd argue that if the keycloak teams feels comfortable to release the docs in this state then it should not be a problem to also host the faulty spec files. And in the end this will only help to get more eyes on them and find all the issues

EDIT: Also some warnings are because the keycloak API in general is implemented "wrong". For example delete operations with bodies are considered against HTTP spec by some generators

I'm still finding (and trying to fix) more discrepancies between the OpenAPI spec and the actual API. I'm fairly certain most endpoints are documented now, but a lot of endpoints are still missing annotations in the source code to document the possible API responses.
As it stands right now, I personally feel like the OpenAPI spec is still more of a preview feature. I very much appreciate the raw spec files being added to releases and the rest-api docs but they probably should be accompanied by an explicit warning about their incompleteness.

IMO, it should be a preview feature. This is because there are warnings by following the OpenAPI notation and some deviations from the implementation.
However, I understand that these warnings and mistakes were latent in the existing HTML API specification, and have become more obvious by generating OpenAPI. So I believe that making it public and having more people contribute to the warnings and mistakes that have surfaced will improve the quality of the REST API, so it is worth making it public, even if it is just a preview feature.

I am also using the openapi spec in my project. I had to manually fix a few things:

1. POST for /admin/realms/{realm}/client-scopes response adjusted to be 201 (openapi spec said it was 200)
2. PUT for /admin/realms/{realm}/client-scopes/{id} response adjusted to be 204 (openapi spec said it was 200)
3. DELETE for /admin/realms/{realm}/client-scopes/{id} response adjusted to be 204 (openapi spec said it was 200)
4. POST for /admin/realms/{realm}/client-scopes/{id}/protocol-mappers/models response adjusted to be 201 (openapi spec said it was 200)
5. /admin/realms/{realm}/client-scopes/{id}/protocol-mappers/models/{id} has 2 times the same parameter. I changed the name of the first one to scopeId
6. POST /admin/realms/{realm}/clients response adjusted to be 201 (openapi spec said it was 200)
7. PUT /admin/realms/{realm}/clients-initial-access/{id} response adjusted to be 204 (openapi spec said it was 200)
8. In ClientRepresentation the property oauth2DeviceAuthorizationGrantEnabled was not known by the api. I removed it from the spec
9. In RealmRepresentation the properties oAuth2DeviceCodeLifespan and oAuth2DevicePollingInterval were included twice. I removed the duplicates.

There are probably more problems. I only changed the endpoints i am actually using.

Thank you for all the feedback. I'll look into how to change this PR's content so that it shows this as a preview.

While I'm doing it, please submit PRs to update the OpenAPI spec generation. As usual, small issues and PRs that focus on one topic at a time are preferred. If you want to work in pairs on this and have a community member review it, it might free up maintainer's time to work on other things / might get you ahead in the queue.

To coordinate, there is already discussion here, so you can drop a note once you have a PR and are looking for another community member: #8898

Be aware that there is a discussion about a v2 Admin API. But as that is not around the corner, we would all benefit from improving the existing documentation in the time being: #8983

I've updated this PR to include the following message, see screenshot below.

Please comment here if you agree/disagree with this change. It will then be included in the KC24 community release.

@ahus1 LGTM

@mhajas - could you please review approve and merge this PR that has been reviewed by the community? Thanks!