OpenAPI document endpoints by joemahady-comm · Pull Request #3689 · cloudfoundry/uaa

joemahady-comm · 2025-12-02T15:20:10Z

Draft pull request testing the generation of OpenAPI document endpoints.

fhanik · 2026-02-02T14:24:12Z

uaa/src/main/java/org/cloudfoundry/identity/uaa/OpenApiConfiguration.java

+                                - Multi-tenancy via identity zones
+                                - Client application management                                
+                                """)
+                        .version("1.0.0")


Maybe list the actual UAA version here? See org.cloudfoundry.identity.uaa.home.BuildInfo bean

fhanik · 2026-02-02T14:25:30Z

uaa/src/main/java/org/cloudfoundry/identity/uaa/OpenApiConfiguration.java

+                                .url("https://www.apache.org/licenses/LICENSE-2.0")))
+                .servers(List.of(
+                        new Server()
+                                .url("http://localhost:8080/uaa")


We can use the actual URL here, see the two beans

@Autowired UaaProperties.Uaa uaaProps; @Autowired UaaProperties.Login loginProps;

Copilot

Pull request overview

This pull request adds OpenAPI 3.0 documentation support to the UAA server using springdoc-openapi library. It enables interactive API documentation through Swagger UI, making it easier for developers to understand and test UAA endpoints.

Changes:

Added springdoc-openapi library dependency (version 2.7.0) to support OpenAPI documentation generation
Created OpenApiConfiguration class to define API metadata, security schemes, and server information
Configured springdoc endpoints in uaa.yml for API docs and Swagger UI access
Added OpenAPI documentation endpoints to the security filter whitelist to make them publicly accessible

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
dependencies.gradle	Adds springdoc-openapi-starter-webmvc-ui:2.7.0 library definition
uaa/build.gradle	Includes springdoc-openapi dependency in the uaa module
server/build.gradle	Includes springdoc-openapi dependency in the server module
uaa/src/main/java/org/cloudfoundry/identity/uaa/OpenApiConfiguration.java	Configures OpenAPI 3.0 metadata, including API info, contact details, license, and OAuth2 security scheme
uaa/src/main/resources/uaa.yml	Configures springdoc endpoints for API docs (/v3/api-docs) and Swagger UI (/swagger-ui.html) with sorting and display options
server/src/main/java/org/cloudfoundry/identity/uaa/SpringServletXmlSecurityConfiguration.java	Whitelists OpenAPI documentation endpoints to allow public access without authentication

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-04T18:50:41Z

uaa/src/main/java/org/cloudfoundry/identity/uaa/OpenApiConfiguration.java

+                                """)
+                        .version(buildInfo.getVersion())
+                        .contact(new Contact()
+                                .name("Cloudfoundry Foundation")


The spelling of "Cloudfoundry" should be "Cloud Foundry" (with a space) to match the consistent spelling used throughout the codebase. All other occurrences in the repository use "Cloud Foundry" with a space.

Suggested change

.name("Cloudfoundry Foundation")

.name("Cloud Foundry Foundation")

Copilot · 2026-02-04T18:50:41Z

uaa/src/main/java/org/cloudfoundry/identity/uaa/OpenApiConfiguration.java

+@Configuration
+public class OpenApiConfiguration {
+
+    private final BuildInfo buildInfo;
+
+    public OpenApiConfiguration(BuildInfo buildInfo) {
+        this.buildInfo = buildInfo;
+    }
+
+    @Bean
+    public OpenAPI uaaOpenAPI() {
+        return new OpenAPI()
+                .info(new Info()
+                        .title("UAA API Reference")
+                        .description("""
+                                UAA (User Account and Authentication) is an OAuth2/OpenID Connect server 
+                                for centralized identity management. This API reference provides endpoints 
+                                for managing users, groups, and client applications.
+
+                                Key Features:
+                                - OAuth2 & OpenID Connect authentication
+                                - SCIM 2.0 user and group management
+                                - Identity provider integration (SAML, LDAP, OIDC)
+                                - Multi-tenancy via identity zones
+                                - Client application management                                
+                                """)
+                        .version(buildInfo.getVersion())
+                        .contact(new Contact()
+                                .name("Cloudfoundry Foundation")
+                                .url("https://github.com/cloudfoundry/uaa"))
+                        .license(new License()
+                                .name("Apache 2.0")
+                                .url("https://www.apache.org/licenses/LICENSE-2.0")))
+                .servers(List.of(
+                        new Server()
+                                .url(buildInfo.getUaaUrl())
+                                .description("UAA Server")
+                ))
+                .addSecurityItem(new SecurityRequirement().addList("bearerAuth"))
+                .components(new Components()
+                        .addSecuritySchemes("bearerAuth", new SecurityScheme()
+                                .type(SecurityScheme.Type.HTTP)
+                                .scheme("bearer")
+                                .bearerFormat("JWT")
+                                .description("""
+                                        OAuth2 Bearer token (JWT format).
+
+                                        Required scopes vary by endpoint:
+                                        - OAuth/Token: uaa.admin, clients.admin
+                                        - Users/Groups: scim.read, scim.write, groups.update
+                                        - Clients: clients.read, clients.write, clients.admin
+                                        - Identity Zones: zones.read, zones.write, uaa.admin
+                                        - Identity Providers: idps.read, idps.write
+
+                                        Obtain tokens via /oauth/token endpoint.
+                                        """)));
+    }
+}


The OpenApiConfiguration class lacks test coverage. Other configuration classes in the same package (like UaaStatsdConfiguration) have corresponding test files. Consider adding a test class to verify that the OpenAPI bean is configured correctly with the expected metadata from BuildInfo.

Copilot · 2026-02-04T18:50:42Z

server/src/main/java/org/cloudfoundry/identity/uaa/SpringServletXmlSecurityConfiguration.java

+            // OpenAPI documentation endpoints
+            "/v3/api-docs/**",
+            "/v3/api-docs", 
+            "/v3/api-docs.yaml",
+            "/swagger-ui/**",
+            "/swagger-ui.html",


The OpenAPI documentation endpoints are being exposed without authentication. While this is common practice for API documentation, it should be a deliberate decision. Consider whether sensitive information about the API structure (like endpoint paths, parameter names, or response schemas) should be publicly accessible. If this is intentional, it's acceptable. However, if there are security concerns, consider restricting access to authenticated users or specific IP ranges.

Suggested change

// OpenAPI documentation endpoints

"/v3/api-docs/**",

"/v3/api-docs",

"/v3/api-docs.yaml",

"/swagger-ui/**",

"/swagger-ui.html",

Copilot · 2026-02-04T18:50:42Z

uaa/src/main/resources/uaa.yml

+  show-actuator: false
+  default-consumes-media-type: application/json
+  default-produces-media-type: application/json
+  disable-swagger-default-url: true


The property "disable-swagger-default-url" is duplicated. It appears both at line 604 under "swagger-ui" and at line 611 at the root "springdoc" level. Since this property is already set at line 604 under the swagger-ui configuration section, the duplicate at line 611 should be removed to avoid redundancy and potential confusion.

Suggested change

disable-swagger-default-url: true

[TNZ-70080]: Testing OpenAPI document endpoints

d2d9fc2

cf-foundation-community-automation bot added this to Foundational Infrastructure Working Group Dec 2, 2025

cf-foundation-community-automation bot moved this to Inbox in Foundational Infrastructure Working Group Dec 2, 2025

joemahady-comm added 5 commits January 28, 2026 13:45

[TNZ-70080]: refactored openapi spec generation

f0b28f0

[TNZ-70080]: refactored openapi spec generation

910bf1b

[TNZ-70080]: refactored openapi spec generation

59bc5ea

[TNZ-70080]: refactored openapi spec generation

7fbdb1b

[TNZ-70080]: refactored openapi spec generation

64f2087

fhanik reviewed Feb 2, 2026

View reviewed changes

[TNZ-70080]: utilise buildInfo to populate version and url

e128cdc

fhanik changed the title ~~[TNZ-70080]: Testing OpenAPI document endpoints~~ Testing OpenAPI document endpoints Feb 3, 2026

duanemay changed the title ~~Testing OpenAPI document endpoints~~ OpenAPI document endpoints Feb 3, 2026

duanemay and others added 3 commits February 3, 2026 12:43

Merge branch 'develop' into TNZ-70080

3393886

OpenAPI document endpoints, update yaml files

8251163

Merge remote-tracking branch 'fork/TNZ-70080' into TNZ-70080

ad91f90

duanemay marked this pull request as ready for review February 4, 2026 18:43

Copilot AI review requested due to automatic review settings February 4, 2026 18:43

Copilot started reviewing on behalf of duanemay February 4, 2026 18:44 View session

Copilot AI reviewed Feb 4, 2026

View reviewed changes

OpenAPI document endpoints, added tests

4c4f79c

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

OpenAPI document endpoints#3689

OpenAPI document endpoints#3689
joemahady-comm wants to merge 11 commits intocloudfoundry:developfrom
joemahady-comm:TNZ-70080

joemahady-comm commented Dec 2, 2025

Uh oh!

fhanik Feb 2, 2026

Uh oh!

fhanik Feb 2, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 4, 2026

Uh oh!

Copilot AI Feb 4, 2026

Uh oh!

Copilot AI Feb 4, 2026

Uh oh!

Copilot AI Feb 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	.name("Cloudfoundry Foundation")
	.name("Cloud Foundry Foundation")

Conversation

joemahady-comm commented Dec 2, 2025

Uh oh!

fhanik Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

fhanik Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants