Swagger API Doku documentation

Swagger Api Doku zu Node Server hinzufügen

Ich habe vor kurzem einen Node Server mit express.js in Typescript programmiert. Das ist eine typische Kombination für Backend Entwicklung. Das ist besonders vorteilhaft wenn bereits Erfahrung mit Frontend Entwicklung in Typescript vorhanden ist. Generell würde ich sowohl im Frontend als auch im Backend empfehlen lieber Typescript anstelle von Javascript zu nutzen. Typescript nutzt Javascript ist aber typbasiert und daher nicht so fehleranfällig!

Auch sollte der Fokus stehts auf clean Code legen und dieser ordentlich dokumentiert sein, besonders wenn ein Projekt größer wird zahlt sich ordentlich dokumentierte Arbeit aus. Um beispielsweise REST Endpunkte zu dokumentieren empfiehlt es sich Swagger zu benutzen. Die Swagger API Dokumentation bietet eine Übersicht über alle Endpunkte und sogar die Möglichkeit mit diesen zu interagieren.

Das könnte Sie auch interessieren: Angular Form SVG mit clickbaren Elementen

Liste der Komponenten

  • Entwicklungsumgebung (z.B. VS Code)
  • Node.js

Dokumentation mit Swagger

Obwohl Swagger recht bekannt ist, konnte ich keine detaillierte Anleitung für die Implementation finden. Ich möchte daher 2 Wege zur Implementierung von Swagger in einen bestehenden Node Server erklären. Die erste Möglichkeit besteht darin direkt zu jedem Endpunkt Swagger Parameter hinzuzufügen. Das ist wohl die schnellere Variante, kann allerdings abhängig von der Anzahl der Endpunkte unübersichtlich werden. In der zweiten Variante wird eine „swagger.json“ Datei erstellt, die die  Parameter der Endpunkte zusammenfasst.

Um Swagger nutzen zu können wird folgende Bibliothek bzw. deren Typerweiterung genutzt:

npm install --save  swagger-ui-express
npm install --save-dev @types/swagger-ui-express

Swagger erstellt eine Dokumentation der Endpunkte:

Example Swagger Docu

Diese können geöffnet werden und man sieht einen beispielhaften Request und einen beispielhaften Response:

Example Swagger Endpoint 1Example Swagger Endpoint 2

Über den Button „Try it out“ kann direkt mit dem Endpunkt interagiert werden.

Swagger API Dokumentation mit Parametern

Diese Variante empfiehlt sich eher für kleinere Projekte. Zunächst müssen diese beiden Swagger Bibliotheken in das Projekt eingebunden werden:

npm install --save-dev @types/swagger-jsdoc 
npm install --save swagger-jsdoc

Die Bibliotheken werden in app.ts bzw. für nicht Typescript Nutzer app.js konfiguriert. Aufgrund der hier festgelegten Konfiguration befindet sich die Dokumentation unter „/api-docs“:

import express from "express";
import bodyParser from "body-parser";
import exampleRoutes from "./routes/example-route";
import swaggerJSDoc from "swagger-jsdoc";
import swaggerUi from "swagger-ui-express";

const app = express();

const options = {
  definition: {
    openapi: "3.0.1",
    info: {
      title: "REST API for Swagger Documentation",
      version: "1.0.0",
    },
    schemes: ["http", "https"],
    servers: [{ url: "http://localhost:3000/" }],
  },
  apis: [
    `${__dirname}/routes/example-route.ts`,
    "./dist/routes/example-route.js",
  ],
};

const swaggerSpec = swaggerJSDoc(options);

app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerSpec));
app.use(bodyParser.json());
app.use(exampleRoutes);

app.listen(3000);

Der Endpunkt wird mit den Parametern folgendermaßen beschrieben:

import { Router } from "express";
import { exampleFunction } from "../controller/example";

const router = Router();

/**
 * @swagger
 * /example:
 *      post:
 *          summary: Send the text to the server
 *          tags:
 *              - ExampleEndpoints
 *          description: Send a message to the server and get a response added to the original text.
 *          requestBody:
 *              required: true
 *              content:
 *                  application/json:
 *                      schema:
 *                          type: object
 *                          properties:
 *                              responseText:
 *                                  type: string
 *                                  example: This is some example string! This is an endpoint
 *          responses:
 *              201:
 *                  description: Success
 *                  content:
 *                      application/json:
 *                          schema:
 *                              type: object
 *                              properties:
 *                                  text:
 *                                      type: string
 *                                      example: This is some example string!
 *              404:
 *                  description: Not found
 *              500:
 *                  description: Internal server error
 */
router.post("/example", exampleFunction);

export default router;

Swagger API Dokumentation mit swagger.json

Um eine bessere Übersicht zu haben und um die Dokumentation nicht mit dem eigentlichen Code zu vermischen empfiehlt sich die Nutzung einer, oder gar mehrerer json Dateien. Bei der Nutzung von TypeScript muss die Swagger.json Datei in die rootDirectory:

Foulder Structure with Swagger.json

Auch hier wirdzunächst die Konfiguration in app.ts bzw. für nicht Typescript Nutzer in app.js festgelegt. Hier wird ebenfalls der Domainpfad „/api-docs“ für die Dokumentation gewählt:

import express from "express";
import bodyParser from "body-parser";
import exampleRoutes from "./routes/example-route";
import swaggerUi from "swagger-ui-express";

import * as swaggerDocument from "./swagger.json";

const app = express();

app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerDocument));

app.use(bodyParser.json());

app.use(exampleRoutes);

app.listen(3000);

Wichtiger Hinweis: Um JSON Dateien in ein Typescript Projekt zu importieren muss dies in der tsconfig.json erlaubt werden. Außerdem muss die JSON Datei sich in der root directory befinden:

{
  "compilerOptions": {
    "target": "es2016" /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */,
    "module": "commonjs" /* Specify what module code is generated. */,
    "rootDir": "./src" /* Specify the root folder within your source files. */,
    "moduleResolution": "node" /* Specify how TypeScript looks up a file from a given module specifier. */,
    "resolveJsonModule": true /* Enable importing .json files. */,
    "outDir": "./dist" /* Specify an output folder for all emitted files. */,
    "esModuleInterop": true /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */,
    "forceConsistentCasingInFileNames": true /* Ensure that casing is correct in imports. */,
    "strict": true /* Enable all strict type-checking options. */,
    "skipLibCheck": true /* Skip type checking all .d.ts files. */
  }
}

Die vorherige Swagger Dokumentation mit Parametern würde somit in der swagger.json folgendermaßen aussehen:

{
  "openapi": "3.0.1",
  "info": {
    "title": "REST API for Swagger Documentation",
    "version": "1.0.0"
  },
  "schemes": ["http"],
  "servers": [{ "url": "http://localhost:3000/" }],
  "paths": {
    "/example": {
      "post": {
        "tags": ["ExampleEndpoints"],
        "summary": "Send a text to the server",
        "description": "Send a message to the server and get a response added to the original text.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExampleSchemaHeader"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExampleSchemaBody"
                }
              }
            }
          },
          "404": { "description": "Not found" },
          "500": { "description": "Internal server error" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ExampleSchemaBody": {
        "properties": {
          "responseText": {
            "type": "string",
            "example": "This is some example string! This is an endpoint"
          }
        }
      },
      "ExampleSchemaHeader": {
        "required": ["text"],
        "properties": {
          "text": {
            "type": "string",
            "example": "This is some example string!"
          }
        }
      }
    }
  }
}

Dateien zum Herunterladen

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert