Verwendung der Swagger UI in Grails

von Tobias Kraft

Ist die Schnittstelle eines Systems mithilfe von OpenAPI beschrieben, kommt in vielen Fällen Swagger UI für die Visualisierung der Dokumentation zum Einsatz. Swagger UI oder der Swagger Editor können online genutzt werden oder als eigenständiges Programm installiert werden. Die JSON- oder YAML-Datei mit der Schnittstellendefinition wird schließlich einfach durch Angabe der URL oder kopieren importiert.

Schöner ist es allerdings, wenn die Dokumentation direkt auf dem gleichen System wie die Schnittstelle verfügbar ist. Dadurch kann sichergestellt werden, dass die Versionen für Beschreibung und Schnittstelle übereinstimmen. Außerdem bleiben potenzielle CORS-Probleme beim Aufruf der API über die Dokumentation erspart.

Frameworks wie Springboot oder Micronaut bieten entsprechende Module an, sodass die Swagger UI Oberfläche direkt integriert ist und zusammen mit dem JAR-File ausgeliefert wird.

Das Fullstackframework grails basiert auf Springboot. Die Nutzung der Spring-Bibliotheken funktioniert jedoch nicht ohne weiteres, da grails zum Beispiel nicht Jackson zur Verarbeitung von JSON verwendet.
Zudem würden neue JAR Abhängigkeiten, wie bspw. das in grails standardmäßig nicht genutzte Jackson, hinzukommen und dadurch das Build-Artefakt erheblich vergrößern.

Alternative Integrationsmöglichkeit

Für die Nutzung der Swagger UI stellt sich also die Frage nach einer Alternative. Da die Swagger UI selbst eine reine UI Anwendung ist, kann die Integration der UI über das Asset-Pipeline Plugin erfolgen. Mit dem Asset-Pipeline Plugin können Ressourcen wie JavaScript und CSS für JVM Applikationen verwaltet und verarbeitet werden.

Für die Integration wird hierfür die HTML-Einstiegsseite der Swagger UI Oberfläche um entsprechende Tags der Asset-Pipeline erweitert. Diese Tags bündeln wie nachfolgend dargestellt sämtliche JavaScript und CSS Ressourcen.

<html lang="en">
  <head>
    <asset:stylesheet src="swagger-ui.scss"/>
    <asset:link rel="icon" type="image/png" href="swagger/favicon-32x32.png" sizes="32x32" />
    <asset:link rel="icon" type="image/png" href="swagger/favicon-16x16.png" sizes="16x16" />
  </head>
  <body>
    <div id="swagger-ui"></div>
    <asset:javascript src="swagger-ui.js"/>
    <script>
    window.onload = function() {
      // Begin Swagger UI call region
      const ui = SwaggerUIBundle({
      	// the URL is provided via the grails controller
        url: "${swaggerUrl}",
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      });
      // End Swagger UI call region

      window.ui = ui;
    };
  </script>
  </body>
</html>

Die API Definition (YML- oder JSON-Datei) wird mit dem Build-Artefakt ausgeliefert und von Swagger UI Oberfläche referenziert. Dies wird über einen einfachen Controller erreicht, der API-Definition für den Download verfügbar macht und zum anderen die UI-Oberfläche ausliefert.

class SwaggerUIController {

    LinkGenerator grailsLinkGenerator

    def index() {
        String swaggerUrl = grailsLinkGenerator.link(action: 'definition', params: [filename: "api.yml"])
        render(view: "index", model:[swaggerUrl: swaggerUrl])
    }

    def definition(String filename) {
        // read Open API definition file and deliver it
        ...
    }

}

Durch die Nutzung eines Controllers ist es nun auch sehr einfach über Annotationen einen individuellen Berechtigungsschutz einzuführen.

Zusammenfassung

Mit der Verwendung des Asset-Pipeline Plugins ist eine einfache und schnelle Integration für die Visualisierung von Open API Dokumentationen möglich. Außerdem werden keine unnötigen JAR-Abhängigkeiten dem Build-Artefakt hinzugefügt.

Zurück