Wie füge ich kleinere Anpassungen in die Swagger-Benutzeroberfläche innerhalb ihres Markups ein?

Lesezeit: 4 Minuten

Benutzer-Avatar
Konrad Viltersten

Ich habe ein .NET Core-Projekt, das mit Swashbuckle dokumentiert ist (Swashbuckle.AspNetCore.SwaggerGen 3.0.0 und Swashbuckle.AspNetCore.SwaggerUi 3.0.0). Mein Ziel ist es, ein benutzerdefiniertes Tag direkt unter dem DIV mit der Klasse hinzuzufügen Titel (dh unter dem Namen des Dienstes, aber über den Endpunkten).

Wenn ich das Swagger-UI-Markup untersuche, sehe ich, dass es ein DIV mit Klasse gibt Prahlerei-ui und ich möchte sozusagen meine Sachen hineinstecken. Das Setup, das ich heute habe, ist eine Datei namens esel.html die gerendert wird, wenn ich auf die URL der Swagger-Benutzeroberfläche zugreife, die wie folgt aussieht.

...
<body>
  <div id="swagger-ui"></div>
  <div id="api_info"></div>
  <!-- ... -->
  <script src="./swagger-ui-bundle.js"></script>
  <script src="./swagger-ui-standalone-preset.js"></script>
  <script type="text/javascript">
    (function () { ... })();
  </script>
</body>
</html>

Ich habe jetzt ein paar Stunden gegoogelt und unter anderem viel über OpenAPI und YAML gelesen. Ich habe jedoch den Eindruck, dass es einen kompletten Neuaufbau des Swagger-UI-Projekts erfordert und mein Ehrgeiz im Moment auf eine viel einfachere Aufgabe abzielt.

Gibt es eine Möglichkeit, das genannte DIV zu buchsen api_info es wird also als Teil von gerendert swagger_ui ohne das gesamte Swagger-UI-Projekt neu zu generieren?

Ich habe versucht, das Basislayout wie gezeigt zu erweitern hier aber das endete schlecht und stellte sich als etwas komplizierter heraus als das, was ich anstrebte. Vielleicht ist es der einzig mögliche Ansatz, ein Modul zu erstellen, in diesem Fall werde ich es in Betracht ziehen, aber das ist in diesem Fall die letzte Ressource.

  • Verwenden Sie Swagger UI 3.x oder 2.x? Ich meine die Benutzeroberfläche selbst, nicht die .NET-Bibliotheken; sehen Versionserkennung. Wenn Sie sich nicht sicher sind, fügen Sie bitte einen Screenshot Ihrer Swagger-Benutzeroberfläche hinzu und zeigen Sie an, wo Sie zusätzliche Inhalte einfügen möchten.

    – Helen

    12. Oktober 2018 um 11:19 Uhr

  • @Helen Ich kann bestätigen, dass es die v3 ist, mit der ich spiele (Antwortobjekt ist {“swaggerUi”:{“version”:”3.17.1″,”gitRevision”:”g24faa46″,”gitDirty”:true,”buildTimestamp”:”Sa, 16. Juni 2018 07:51:13 GMT”,”machine “:”travis-job-311a007d-ebec-4b3c-bc7e-58ad5df1e1d8”}}). Was die Platzierung des DIV betrifft, möchte ich die Steuerung mit ID #api_info direkt unter oder über dem Titel gerendert werden (z. B. “Swagger Zoohandlung” unter dem Link, den Sie uns freundlicherweise zur Verfügung gestellt haben).

    – Konrad Viltersten

    12. Oktober 2018 um 12:16 Uhr

  • @Helen Ich habe vergessen zu erwähnen, dass ich versucht habe, das Standardlayout zu erweitern, wie in der Bearbeitung meiner Frage. Allerdings geht es darum, ein Plugin für Swagger zu erstellen, was für einen so kleinen Eingriff, den ich versuche, ein bisschen übertrieben zu sein scheint.

    – Konrad Viltersten

    12. Oktober 2018 um 14:37 Uhr

Swagger UI 3.x verfügt über das Plugin-System, mit dem Sie UI-Elemente hinzufügen oder ändern können. Einige Dokumentationen zu Plugins finden Sie unter:
Plugins
Wie soll SwaggerUI 3.x angepasst werden?

Es ist nicht erforderlich, die Swagger-Benutzeroberfläche neu zu kompilieren, um Plugins zu verwenden, Sie können die Plugins tatsächlich direkt in der definieren index.html Seite. Um UI-Elemente hinzuzufügen oder zu ändern, benötigen Sie ein Plugin, das verwendet wrapComponents und React.createElement um die gewünschte DOM-Struktur aufzubauen. (Siehe auch Reagieren ohne JSX.)

Damit die benutzerdefinierten Plugins wirksam werden, müssen sie der hinzugefügt werden plugins Liste in der SwaggerUIBundle Konstrukteur.

Beispiel

Hier ist ein Beispiel-Plugin, das benutzerdefinierte hinzufügt <h3> Kopfzeilen über und unter dem API-Titel:

// index.html

<script>
window.onload = function() {

  // Custom plugin that adds extra stuff
  const MyCustomPlugin = function() {
    return {
      wrapComponents: {
        // add text above InfoContainer - same effect as above title
        InfoContainer: (Original, { React }) => (props) => {
          return React.createElement("div", null,
            React.createElement("h3", null, "I'm above the InfoContainer"),
            React.createElement(Original, props)
          )
        },

        // and/or add text above API description
        InfoUrl: (Original, { React }) => (props) => {
          return React.createElement("div", null,
            React.createElement(Original, props),
            React.createElement("h3", null, "I'm above the API description")
          )
        }
      }
    }
  }


  const ui = SwaggerUIBundle({
    url: "http://petstore.swagger.io/v2/swagger.json",
    dom_id: '#swagger-ui',
    ...
    plugins: [
      MyCustomPlugin,       // <------ add your custom plugin here
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    ...

Das Ergebnis sieht so aus:

Swagger-UI mit angepasstem Layout

1017150cookie-checkWie füge ich kleinere Anpassungen in die Swagger-Benutzeroberfläche innerhalb ihres Markups ein?

This website is using cookies to improve the user-friendliness. You agree by using the website further.

Privacy policy