Der Eintrag "offcanvas-col1" existiert leider nicht.

Der Eintrag "offcanvas-col2" existiert leider nicht.

Der Eintrag "offcanvas-col3" existiert leider nicht.

Der Eintrag "offcanvas-col4" existiert leider nicht.

Die Telefonnummer wird mit JavaScript generiert.

Verwendung der Swagger UI in Grails

von

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.

Kategorien: GrailsGroovyRESTSpring Boot

Zurück

© 2022 exensio GmbH
Einstellungen gespeichert
Datenschutzeinstellungen

Wir nutzen Cookies auf unserer Website. Einige von ihnen sind essenziell, während andere uns helfen, diese Website und Ihre Erfahrung zu verbessern.

Sie können Ihre Einwilligung jederzeit ändern oder widerrufen, indem Sie auf den Link in der Datenschutzerklärung klicken.

Zu den gesetzlichen Rechenschaftspflichten gehört die Einwilligung (Opt-In) zu protokollieren und archivieren. Aus diesem Grund wird Ihre Opt-In Entscheidung in eine LOG-Datei geschrieben. In dieser Datei werden folgende Daten gespeichert:

 

  • IP-Adresse des Besuchers
  • Vom Besucher gewählte Datenschutzeinstellung (Privacy Level)
  • Datum und Zeit des Speicherns
  • Domain
You are using an outdated browser. The website may not be displayed correctly. Close