[Roast: Day – Automatisches Erstellen eines API-Servers ohne KI

Um meine Frontend-Schnittstelle mit der Datenbank zu verbinden, muss ich eine API entwerfen, die es der Frontend-Anwendung ermöglicht, Daten abzurufen und zu senden. Dadurch wird meine Benutzerlogik aktiviert, z. B. das Erstellen von Konten, das An- und Abmelden usw. Es wird die gesamte Logik rund um Röstungen aktiviert.

Ich habe schon einmal eine Express-API erstellt, aber dieses Mal wollte ich sehen, ob ich im Build-Prozess etwas mehr über Swagger lernen kann.

Die Swagger-Suite

Swagger ist ein Unternehmen, das drei Produkte entwickelt und pflegt: den Swagger Editor, Swagger CodeGen und Swagger UI. Diese drei Produkte arbeiten Hand in Hand, um die Erstellung einer OpenAPI-kompatiblen Anwendung (und der Dokumentation) einfacher zu machen!

Einen Vertrag verwenden

Der Prozess der Verwendung von Swagger zum Erstellen einer API beginnt mit dem Swagger-Editor. Mit diesem Tool können Sie einen sogenannten Vertrag erstellen. Der Vertrag ist ein YAML-Dokument, das verschiedene Dinge über die Anwendung definiert, wie den Namen, die zu verarbeitenden Routen usw.

YAML vs. JSON

Wenn Sie noch nie mit YAML gearbeitet haben: Es handelt sich um eine lockerere objektbasierte Auszeichnungssprache, die einige Ähnlichkeit mit JSON aufweist, sich aber viel einfacher schnell eintippen lässt. Hier ist ein Beispiel für denselben Inhalt in JSON und dann in YAML:

// JSON Example
{
  "name": "ThisApp",
  "description": "An example of data.",
  "list": [
    "option1",
    "option2",
    "option3"
  ],
  "object": {
    "key": "value"
  }
}

# YAML Example
name: ThisApp
description: An example of data.
list:
  - option1
  - option2
  - option3
object:
  key: value

Beachten Sie, dass YAML zwar immer noch maschinenlesbar ist, aber auch für Menschen etwas einfacher zu lesen ist, was es zu einer großartigen Auszeichnungssprache für diese Spezifikation macht.

Definieren von API-Spezifikationen

Mit dem Swagger-Editor und der Befolgung von OAS können Sie alles schreiben, was Sie normalerweise in eine API programmieren würden.

Auf der obersten Ebene definieren Sie die Besonderheiten der Anwendung:

openapi: 3.0.3
info:
  title: Roast - Know Your Home Roasts
  description: # This will appear in the API UI
  version: 1.0.0
servers:
  - url: # A url to one or more servers here
tags:  These are groups of paths
  - name: user
    description: Operations for your user
  - name: roast
    description: Access to roasts
paths:
  # Define all of your paths in this object
components:
  # Define reusable pieces of code here

Die Magie des CodeEditors erwacht zum Leben, wenn Sie mit der Definition von Pfaden beginnen. Nehmen Sie den folgenden Pfad, den ich definiert habe, um einen einzelnen Braten nach ID zu erhalten.

# ... contract information
paths:
  # ... users paths, etc.
  /roasts/{roastId}:
    get:
      tags:
        - roast
      summary: Get roast by id
      description: Must include a valid roast id
      parameters:
        - $ref: '#/components/parameters/roastIdParam'
      responses:
        '200': 
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Roast"
        '400':
          $ref: '#/components/responses/Invalid'
        '404':
          $ref: '#/components/responses/NotFound'

Lassen Sie uns dieses Objekt aufschlüsseln. Erstens heißt es /roasts/{roastId}. Das bedeutet, dass wir das erwartete Verhalten des Servers definieren, wenn eine Anfrage an diese Route gesendet wird. Was passiert darunter?

• get: Dies teilt den Swagger-Tools mit, dass wir einen GET-Anforderungsendpunkt für diesen Pfad definieren möchten. Der Rest der Informationen über die GET-Anforderung befindet sich in diesem Objekt.
• Tags: Dies ist eine optionale Eigenschaft eines Endpunkts, aber in der Benutzeroberfläche nützlich, da Sie damit Ihre Endpunkte in Ihrer Dokumentation gruppieren können.
• Zusammenfassung: und Beschreibung: In der Bildschirmdarstellung der Swagger-Benutzeroberfläche werden Sie diese beiden Felder an unterschiedlichen Stellen sehen. Die Zusammenfassung bietet eine kurze Erläuterung der Funktionalität des Endpunkts und die Beschreibung liefert zusätzliche Details.
• Parameter: In dieser Eigenschaft von get: können die Pfadparameter angegeben werden. Sie können Informationen hinzufügen, z. B. ob der Parameter erforderlich ist oder nicht und welche Art von Daten zu erwarten sind.
• Antworten: Hier ist das Fleisch und die Kartoffeln. Jede gültige Antwort von einem Endpunkt wird als Statuscodezeichenfolge identifiziert und kann hier zu Dokumentations- und Codegenerierungszwecken aufgelistet werden.

Mit Komponenten trocken bleiben

Wenn Sie einen Vertrag wie diesen ausarbeiten, werden Sie wahrscheinlich feststellen, dass Sie immer wieder die gleichen Dinge eingeben. Und als Programmierer wissen Sie vielleicht, dass wir dem DRY-Prinzip folgen wollen: „Don't Repeat Yourself.“ Wenn Sie beispielsweise einen erforderlichen Anforderungstext definieren, gibt es mehrere Endpunkte, die möglicherweise dasselbe Objekt erfordern.

Nun, hier kommen die Komponenten ins Spiel. In diesem Beispiel können Sie ein Schema definieren und dann an einer beliebigen Stelle im Vertrag auf dieses Schema verweisen, indem Sie $ref: .

verwenden

Am Ende meines Vertrags habe ich also eine Komponente: Objekt.

components:
  schemas:
    Roast: # An arbitrary name to identify the schema
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        ## Include all other properties

Dieses Komponentenobjekt enthält ein Schema namens Roast . Wenn ich also jetzt angeben müsste, dass dieses Objekt in einer Anfrage gesendet werden muss, beispielsweise in einer POST-Anfrage an /roast, um einen neuen Roast hinzuzufügen. Ich kann das Objekt folgendermaßen referenzieren:

/roast:
  post:
    # additional specifications
    requestBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Roast'

Sie können dies auch beim Definieren Ihrer Parameter und vieler anderer wiederholter Abschnitte Ihrer Spezifikation tun!

Automatische Dokumentation

Während Sie in Ihrem Swagger-Editor tippen, wird die Swagger-Benutzeroberfläche im Fenster auf der rechten Seite ständig aktualisiert. Swagger UI aktualisiert Ihre künftige API-Dokumentation! Dies bedeutet, dass Sie später nicht noch einmal zurückgehen und die Dokumentation selbst verfassen müssen.

Das Beste daran ist, dass es zusammen mit Ihrer Anwendung bereitgestellt wird (sofern Sie CodeGen zum Erstellen verwenden).

Let Swagger Code Your API Too!

Once you feel like your API is up to spec, you can have a working server in 17 different languages/frameworks in seconds! Just click Generate Server, and select your flavor and CodeGen reads your OAS spec and downloads a server.

In Node, your code comes out in a few different directories.

generated-server/
|-- api/
|-- controllers/
|-- service/
|-- utils/
|-- README.md
|-- index.js
|-- package.json

The api directory contains your OpenAPI spec. The controllers directory contains a file for each of your path groups, with exported functions specifically for handling the unique paths and operations of your application. The service directory, is where you will hook these operations up to your database and perform the business logic of the application, and utils contains functions that help read and write data.

Your server will actually live in index.js.

Is It Really That Easy?

Yes! Well, sort of.

CodeGen does in fact make a working server for you, but it's still up to you to hook up the database and design the logic of the application! But, it gives you a complete and organized skeleton that you can work in!

Here's an example of the code that it output for my POST request to /roasts .

// controllers/Roast.js
// ...
module.exports.addRoast = function addRoast (req, res, next, body) {
  Roast.addRoast(body)
    .then(function (response) {
      utils.writeJson(res, response);
    })
    .catch(function (response) {
      utils.writeJson(res, response);
    });
};

// service/RoastService.js
// ...
exports.addRoast = function(body) {
  return new Promise(function(resolve, reject) {
    var examples = {};
    examples['application/json'] = {
  "notes" : "Doesn't taste as good as last time... I wonder if the weather is making the beans roast faster now that it's warmer",
  "heatLevel" : "Med",
  "origin" : "Ethiopian",
  // ...
  "id" : 10,
};
    if (Object.keys(examples).length > 0) {
      resolve(examples[Object.keys(examples)[0]]);
    } else {
      resolve();
    }
  });
}

The above code was entirely generated by Swagger CodeGen. However, it won't actually add a roast object anywhere. This is creating a mock object and sending it back. But, after hooking up a Postgres database, and creating queries with this logic inside the service, the API will be fully operational!

Would You Use It?

I loved working with Swagger on this API, it was the first time that I committed to learning some of the intricacies of OAS to generate the server. The only rub that I have with it is that the docs are not formatted the best, and they can be hard to navigate searching for what you want to add to the server.

But, once you're familiar with OAS, this tool can save a ton of time. Not only do you have extremely thorough documentation when you're done, but you can treat the generated code as a to-do list of the functions and logic that you need to implement as you build!

Would you give it a try?

---

Check Out the Project

If you want to keep up with the changes, fork and run locally, or even suggest code changes, here’s a link to the GitHub repo!

https://github.com/nmiller15/roast

The frontend application is currently deployed on Netlify! If you want to mess around with some features and see it in action, view it on a mobile device below.

https://knowyourhomeroast.netlify.app

Note: This deployment has no backend api, so accounts and roasts are not actually saved anywhere between sessions.

Das obige ist der detaillierte Inhalt von[Roast: Day – Automatisches Erstellen eines API-Servers ohne KI. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!