7 Einführung in OpenAPI

7.1 Was ist OpenAPI?

OpenAPI, ursprünglich bekannt als Swagger, ist eine Spezifikation zur Beschreibung, Produktion, Konsumation und Visualisierung von RESTful Web Services. OpenAPI definiert einen standardisierten und maschinenlesbaren Format für die Beschreibung von APIs, was die Erstellung von Werkzeugen und Dienstleistungen rund um die API erleichtert.

7.1.1 OpenAPI als Vertrag

In der Welt der Softwareentwicklung bezeichnet der Begriff “Vertrag” eine klar definierte Spezifikation, wie sich eine Software oder ein Softwarekomponente verhalten sollte. In diesem Kontext dient die OpenAPI-Spezifikation als “Vertrag” zwischen den verschiedenen Diensten, die eine API verwenden.

Jeder, der die API verwendet, kann sich auf die OpenAPI-Spezifikation als “Source of Truth” beziehen, um zu verstehen, wie die API funktioniert, welche Anfragen sie akzeptiert und welche Antworten sie liefert. Dies macht die Kommunikation und Koordination zwischen den verschiedenen Teams und Diensten, die die API nutzen, viel einfacher und effizienter.

7.2 Entkopplung durch OpenAPI

OpenAPI ermöglicht eine stärkere Entkopplung zwischen den verschiedenen Teilen eines Systems. Da die Kommunikation zwischen den Diensten durch eine standardisierte Spezifikation definiert ist, können sie unabhängig voneinander entwickelt und gewartet werden, solange sie den in der OpenAPI-Spezifikation festgelegten “Vertrag” einhalten.

7.2.1 Unabhängigkeit vom Technologiestack

Ein weiterer Vorteil von OpenAPI ist, dass es die Kommunikation zwischen Diensten auf der Protokollebene standardisiert. Dies bedeutet, dass die zugrunde liegenden Technologien, die von den verschiedenen Diensten verwendet werden, irrelevant sind, solange sie den OpenAPI-Vertrag einhalten.

So kann beispielsweise ein Dienst, der in Python geschrieben ist, problemlos mit einem Dienst, der in Java geschrieben ist, kommunizieren, solange beide den gleichen OpenAPI-Vertrag verwenden. Dies fördert die Interoperabilität zwischen verschiedenen Technologien und ermöglicht eine größere Flexibilität bei der Auswahl der für eine bestimmte Aufgabe am besten geeigneten Technologie.

7.3 OpenAPI für Dokumentation und Testen

Schließlich erleichtert OpenAPI auch die Dokumentation und das Testen von APIs. Durch die Verwendung von Tools wie Swagger UI können Entwickler interaktive Dokumentationen für ihre APIs erstellen, die auf der OpenAPI-Spezifikation basieren.

Diese Dokumentationen ermöglichen es Benutzern, die API direkt in ihrem Browser zu testen und zu verwenden, was das Verständnis und die Nutzung der API erheblich erleichtert. Darüber hinaus können automatisierte Testwerkzeuge die OpenAPI-Spezifikation verwenden, um Tests zu generieren und die Einhaltung des Vertrags zu überprüfen.

Zusammenfassend lässt sich sagen, dass OpenAPI eine mächtige Spezifikation für die Erstellung, Dokumentation und Testen von RESTful APIs ist, die die Interoperabilität und Flexibilität von Software-Systemen fördert.

7.4 Beispiel

Hier ist ein einfaches OpenAPI-Schema, das eine API beschreibt, mit der man Informationen über Bücher abrufen, erstellen und löschen kann. Es enthält den Meta-Teil, GET-, POST- und DELETE-Endpunkte und separate Modelle.

openapi: 3.0.0
info:
  version: 1.0.0
  title: Simple Book API
  description: A simple API to learn about OpenAPI Specification
servers:
  - url: http://example.com/api/v1

paths:
  /books:
    get:
      summary: Returns a list of books
      responses:
        '200':
          description: A JSON array of book objects
          content:
            application/json:
              schema: 
                type: array
                items: 
                  $ref: '#/components/schemas/Book'

    post:
      summary: Creates a new book
      requestBody:
        description: A JSON object containing book information
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Book'
      responses:
        '201':
          description: Book created successfully

  /books/{bookId}:
    delete:
      summary: Deletes a book
      parameters:
        - in: path
          name: bookId
          schema:
            type: integer
          required: true
          description: The id of the book to delete
      responses:
        '204':
          description: Book deleted successfully

components:
  schemas:
    Book:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the book
        title:
          type: string
          description: Name of the book
        author:
          type: string
          description: Author of the book
      required:
        - id
        - title
        - author

In diesem Beispiel wird ein GET-Request verwendet, um eine Liste von Büchern abzurufen, ein POST-Request, um ein neues Buch zu erstellen, und ein DELETE-Request, um ein Buch zu löschen. Jeder Request hat seine eigenen Parameter und Antworten, die in der OpenAPI-Spezifikation definiert sind.

Darüber hinaus enthält das Schema einen “components” Abschnitt, in dem die Modelle für die API definiert sind. In diesem Fall gibt es nur ein Modell, “Book”, das die Eigenschaften eines Buches definiert.