Feature | Add OpenAPI documentation controller OAuth2UserApiController v2 routes

[matiasperrone-exo]

Task:

Ref: https://app.clickup.com/t/86b7fj5wh

Endpoints affected:

Verbs	Endpoint	Method
GET,HEAD	api/v2/users/{id}	getV2

[martinquiroga-exo]

LGTM

[caseylocker]

1. CRITICAL
   app/Swagger/Security/UsersOAuth2Schema.php uses hardcoded relative paths:

  authorizationUrl: '/oauth2/auth',
  tokenUrl: '/oauth2/token',

Per project conventions like in summit-api, these must use the L5-Swagger constants:

  authorizationUrl: L5_SWAGGER_CONST_AUTH_URL,
  tokenUrl: L5_SWAGGER_CONST_TOKEN_URL,

The .env.example already defines L5_SWAGGER_CONST_AUTH_URL and L5_SWAGGER_CONST_TOKEN_URL, and the config registers them under defaults.constants. Hardcoding defeats the purpose of environment-specific URLs.

app/Http/Controllers/Api/OAuth2/OAuth2UserApiController.php
The getV2 route in routes/api_v2.php is wrapped in service.account middleware:

Route::get('', ['middleware' => 'service.account', 'uses' => 'OAuth2UserApiController@getV2']);

The OpenAPI attribute on getV2 has summary: 'Get a user by ID' but no description mentioning the middleware requirement. Per conventions, it should include something like:

description: 'Requires service account authentication (middleware: service.account)',

UsersOAuth2Schema.php only defines one scope:

IUserScopes::ReadAll => 'Read All Users Data',

The security scheme definition should include all scopes that will be referenced across User endpoints (not just the one used by this PR's endpoint). Looking at IUserScopes, the scheme should also include at minimum: MeRead, Write, UserGroupWrite, and Registration — any scope that future User/Group endpoints will reference.

config/l5-swagger.php Copy/Paste

'title' => 'Summit API Swagger UI',

Should be 'OpenStackID API Swagger UI' or similar. This is a copy-paste from the summit-api project.

[matiasperrone-exo]

Thanks @caseylocker for the comments.

The response to each point:

1. I've replaced the string by the env variables as requested, this change was also done in all the other PRs: Feat | API OAuth2UserApiController routes v1 #106, Feat | Add OpenAPI documentation for OAuth2UserRegistrationRequestApiController #108, Feat | Add OpenAPI documentation for OAuth2GroupApiController #109, Feat | Add OpenAPI documentation for OAuth2StreamChatSSOApiController #110 that are out there so far.
2. Let me talk with Martin about this, I am not sure if I follow, we never documented middleware in Summit API before, it seems unrelated to OpenAPI documentation standards.
3. The rest of the scopes are present in a different branch feat/openapi----api-v1---oauth2userapicontroller (PR Feat | API OAuth2UserApiController routes v1 #106) as this branch only covers one endpoint.
4. This was fixed on PR Chore | Initial setup for OpenAPI 3.1.2 documentation #103 and rebased in this PR.

1. CRITICAL
   app/Swagger/Security/UsersOAuth2Schema.php uses hardcoded relative paths:

  authorizationUrl: '/oauth2/auth',
  tokenUrl: '/oauth2/token',

Per project conventions like in summit-api, these must use the L5-Swagger constants:

  authorizationUrl: L5_SWAGGER_CONST_AUTH_URL,
  tokenUrl: L5_SWAGGER_CONST_TOKEN_URL,

The .env.example already defines L5_SWAGGER_CONST_AUTH_URL and L5_SWAGGER_CONST_TOKEN_URL, and the config registers them under defaults.constants. Hardcoding defeats the purpose of environment-specific URLs.

app/Http/Controllers/Api/OAuth2/OAuth2UserApiController.php
The getV2 route in routes/api_v2.php is wrapped in service.account middleware:

Route::get('', ['middleware' => 'service.account', 'uses' => 'OAuth2UserApiController@getV2']);

The OpenAPI attribute on getV2 has summary: 'Get a user by ID' but no description mentioning the middleware requirement. Per conventions, it should include something like:

description: 'Requires service account authentication (middleware: service.account)',

UsersOAuth2Schema.php only defines one scope:

IUserScopes::ReadAll => 'Read All Users Data',

The security scheme definition should include all scopes that will be referenced across User endpoints (not just the one used by this PR's endpoint). Looking at IUserScopes, the scheme should also include at minimum: MeRead, Write, UserGroupWrite, and Registration — any scope that future User/Group endpoints will reference.

config/l5-swagger.php Copy/Paste

'title' => 'Summit API Swagger UI',

Should be 'OpenStackID API Swagger UI' or similar. This is a copy-paste from the summit-api project.

[matiasperrone-exo]

@caseylocker I checked and added the legend "(only for service accounts)" to the description