Automatically document required roles in OpenAPI specifications

Aperta
  • Qualcosa non va?
#3,468 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
48/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
java, openapi
Ambito
api, documentation

Direzione di ricerca

Read ManagerWebService.getOpenApiResource() and the resolve configuration in manager/build.gradle to trace runtime and build time OpenAPI generation. Then inspect the JAX-RS resources for @RolesAllowed, including inherited annotations, and check how Swagger Core exposes operations to Swagger UI. Done when both generation paths show the required roles while preserving the existing distinction between roles and OAuth2 scopes.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Documentation

Description

Currently, the generated OpenAPI specifications don't document which roles are required to access individual endpoints, even though these roles are already defined using @RolesAllowed annotations on the JAX-RS resources.

We could use a custom Swagger Core OpenApiReader (configured via readerClass) to automatically extract these roles and include them in the operation descriptions and/or as an OpenAPI extension (e.g. x-roles-allowed).

For example, @RolesAllowed(Constants.READ_ADMIN_ROLE) could produce:

get:
  description: |
    Retrieve the health status of the system.

    **Allowed roles:** `read:admin`
  x-roles-allowed:
    - read:admin

Configuration

The custom reader should be configured for both runtime and build-time OpenAPI generation.

Runtime generation — ManagerWebService.getOpenApiResource():

SwaggerConfiguration oasConfig =
    new SwaggerConfiguration()
        .resourcePackages(Set.of("org.openremote.model.*"))
        .openAPI(loadOpenApiBase())
        .readerClass(RolesOpenApiReader.class.getName())
        .defaultResponseCode("200");

Build-time generation — manager/build.gradle:

resolve {
    // Existing configuration...
    readerClass = 'org.openremote.manager.web.RolesOpenApiReader'
}

These are illustrative configuration snippets; the custom reader still needs to be implemented.

Acceptance criteria

  • Automatically extract roles from method-level and class-level @RolesAllowed annotations, including inherited annotations.
  • Include the roles in operation descriptions and/or as an x-roles-allowed extension.
  • Ensure the roles are visible in Swagger UI.
  • Support both runtime generation in ManagerWebService and build-time generation using the Gradle resolve task.
  • Preserve the existing authentication and authorization behavior, including the distinction between roles and OAuth2 scopes.
  • Avoid duplicating role information in OpenAPI-specific annotations.
Lingua principale
Java
Stelle
1.9k
Fork
478
Nessuna PR unita negli ultimi 30g

Preparare l'ambiente

Apri in Codespaces

Avvia il container di sviluppo del progetto nel browser, con il tuo account GitHub.

  • Include un Dockerfile o un file Docker Compose
  • Ha un modello di pull request
  • Nessuna guida per i contributori

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di openremote/openremote

Tutte le issue di openremote/openremote

Issue simili

Altre issue su Java

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.