How to document the oauth endpoints?

[sskjames]

First of all, thank you very much to all concerned for creating/maintaining this project.
I checked the project documentation on how to document the security endpoints (e.g outh2/token) but I couldn't find much information except the suggestion to include springdoc-openapi-security. It also has this point:
This dependency helps ignoring @AuthenticationPrincipal in case its used on REST Controllers..
It's not clear to me that whether including this dependency will help list the security endpoints in the generated docs. Also I couldn't find info on how to add custom documentation for these security endpoints.
Have I missed something? Can someone please help me?

Thanks
James

[sskjames]

Here is a minimal working sample application.
spring-oauth-springdoc-demo.zip

Basically I'm using:
Spring Boot: 2.7.x
Spring Authorization Server: 0.4.1
SpringDoc: 1.6.14

I'm only able to see only one endpoint (/hello) in the generated doc.
I'd like the /oauth2/token endpoint to be listed in the doc.

[bnasslahsen]

@sskjames,

Spring Authorization Server was not yet supported.
I have added a property to enable the support:

springdoc.show-oauth2-endpoints=true

You can already do your tests with the latest SNAPSHOT and provide your feedback before the next release.

[sskjames]

@sskjames,

Spring Authorization Server was not yet supported. I have added a property to enable the support:

springdoc.show-oauth2-endpoints=true

You can already do your tests with the latest SNAPSHOT and provide your feedback before the next release.

Hi @bnasslahsen, thank you very much for addressing this concern.
I tested this with 1.6.15-SNAPSHOT and I could see all the authorization server endpoints once I configured specified property.
Does springdoc provide the ability to customize the documentation generated for these endpoins just like we do with the @Operation annotation for regular endpoins?

[bnasslahsen]

@sskjames,

You could use GlobalOpenApiCustomizer to adapt the generated openAPI definition. This is the recommended way.
Another alternative, you can use your own bean SpringDocSecurityOAuth2Customizer to override the existing logic.

[uc4w6c]

@bnasslahsen
Thank you for supporting Spring Authorization Server.

The column of response body is camel case, but snake case is actually returned.

example (/.well-known/oauth-authorization-server)

actual response

{
   "issuer": "http://localhost:8080",
   "authorization_endpoint": "http://localhost:8080/oauth2/authorize",
   "token_endpoint": "http://localhost:8080/oauth2/token",
   "token_endpoint_auth_methods_supported": [
     "client_secret_basic",
     "client_secret_post",
     "client_secret_jwt",
     "private_key_jwt"
   ],
   ...
}

api-docs schema

			"OAuth2AuthorizationServerMetadata": {
				"type": "object",
				"properties": {
					"issuer": {
						"type": "string",
						"format": "url"
					},
					"authorizationEndpoint": {
						"type": "string",
						"format": "url"
					},
					"tokenEndpointAuthenticationMethods": {
						"type": "array",
						"items": {
							"type": "string"
						}
					},
					...
				}
			}

---

The springdoc code uses OAuth2AuthorizationServerMetadata when creating a schema, but in AbstractOAuth2AuthorizationServerMetadata inherited by this class, OAuth2AuthorizationServerMetadataClaimNames is used for each column to determine the column name for response.

example

https://github.com/spring-projects/spring-authorization-server/blob/ad01779479d72ede119c1d6110edc3fa9d1bff3a/oauth2-authorization-server/src/main/java/org/springframework/security/oauth2/server/authorization/AbstractOAuth2AuthorizationServerMetadata.java#L96

Therefore, it is difficult to obtain the value, so I think it is better to define the schema for each field.
However, when the Spring Authorization Server changes the response format, the springdoc also needs to be modified, which may be a concern for maintainability.
(Various responses are RFC compliant, so I don't think the response columns change frequently.)
What do you think?

There are a lot of revisions, so if there is anything I can do, I will be happy to help.

[bnasslahsen]

@uc4w6c,

This is the kind of feedback i was expecting.
Agree with your approach.
If you want go for it, please feel free to propose a PR.

[shrralis]

@bnasslahsen is it possible to add support for /.well-known/openid-configuration and other OIDC endpoints of Spring Authorization Server as well?

[uc4w6c]

@shrralis
Already committed. (#2340)
It will be available from the next version.