Praxiswissen: Micronaut Security-Endpunkte mit Swagger dokumentieren
Das Framework Micronaut wurde mit dem Fokus zur Erstellung von Microservices und Serverless Applikationen entwickelt. Deshalb ist das Bereitstellen von Rest-Schnittstellen durch Micronaut ein häufiger Anwendungsfall. Beispiele hierfür sind Schnittstellen für UI-Oberflächen wie SPA (Single Page Webanwendungen) oder Integrationen mit anderen Microservices. Die offerierten Rest-Schnittstellen werden heutzutage in den meisten Fällen mit JSON umgesetzt.
Für die konsumierende Seite ist eine entsprechende Dokumentation essenziell und hierfür hat sich der Standart OpenAPI etabliert. Die Dokumentation erfolgt über YML- bzw. Json-Dateien.
Micronaut ermöglicht wie auch bspw. Spring Boot die automatische Generierung der Dateien aus dem Quellcode. Hierfür werden unter anderem die Deklarationen von Controller-Methoden und deren Annotation zur Hilfe gezogen. Bei Bedarf können zusätzlich spezifische OpenApi Annotationen genutzt werden.
Die generierte Dokumentation kann in der Applikation direkt über Swagger visualisiert werden. Hierfür muss lediglich, wie im nachfolgenden Beispiel für einen Groovy Kompilier-Schritt unter gradle gezeigt, die Konfiguration angepasst werden:
tasks.withType(GroovyCompile) {
options.forkOptions.jvmArgs << '-Dmicronaut.openapi.views.spec=redoc.enabled=false,swagger-ui.enabled=true,swagger-ui.theme=flattop'
}Es kann also für alle selbst implementierten Endpunkte relativ einfach eine Dokumentation bereitgestellt werden, die immer aktuell ist.
Micronaut Security-Endpunkte
Mit Micronaut Security werden für die Authentifizierung und Autorisierung entsprechende Funktionalitäten angeboten. Wird die über swagger-ui generierte Dokumentation betrachtet, fällt auf, dass die Login-Funktionalität nicht automatisch dokumentiert ist, da diese auch im Projekt selbst nicht implementiert wurde. Im Normalfall ist die Authentifizierung der erste Aufruf vor der Verwendung einer API und sollte ebenfalls dokumentiert sein.
Dies erfolgt am einfachsten durch die manuelle Erstellung einer separaten YML-Datei mit den Informationen anhand der Security-Dokumentation. Diese wird im Projekt ablegt.
security.yml
paths:
/api/login:
post:
tags:
- authorization
operationId: login
parameters: []
requestBody:
content:
application/json:
schema:
type: object
properties:
username:
type: string
password:
type: string
required:
- username
- password
required: true
responses:
'200':
description: Successful login to the system
default:
description: Login admin users to the system
Durch entsprechende Referenzierung, wieder am Beispiel von gradle illustriert, fließt die Datei in die Dokumentation mit ein:
tasks.withType(GroovyCompile) {
options.forkOptions.jvmArgs << '-Dmicronaut.openapi.views.spec=redoc.enabled=false,swagger-ui.enabled=true,swagger-ui.theme=flattop'
options.forkOptions.jvmArgs << '-Dmicronaut.openapi.additional.files=src/main/resources/swagger'
}In der swagger-ui Oberfläche ist der Login-Endpunkt anschließend entsprechend sichtbar:
