Dieser Artikel wurde veröffentlicht auf Liferay Community Blog, _ Erstellen kopfloser APIs (Teil 1) Dies ist eine Übersetzung von -headless-apis-part-1) _.

Einführung

Kürzlich habe ich mit Liferays neuer kopfloser API experimentiert. Insbesondere handelt es sich um ein reaktionsbasiertes SAP, das Headless Delivery- und Headless User Management-Module verwendet. Wir werden die Implementierung viermal behandeln, aber dieses Mal zeigen wir Ihnen, wie Sie mit den REST Builder-Tools Ihre eigene kopflose API erstellen.

Möglicherweise haben Sie hier die folgenden Fragen.

"_Warum sollten Sie REST Builder anstelle Ihres eigenen REST verwenden, das auf herkömmlichem JAX-RS basiert? _"

Der REST Builder von Liferay erstellt nicht nur Anwendungen, die Endpunkte verfügbar machen. Es bietet außerdem die folgenden zusätzlichen Funktionen: ::

Integration in die Zertifizierungspipeline von Liferay
Integration mit Liferays Umgang mit CORS
Headless-Funktion zur Unterstützung der Integration in Liferay-Suche, Filterung, Paging und mehr
JSON- oder XML-Generierungsfunktion für Anruferanfragen
Integration mit dem kommenden Liferay GraphQL-Endpunkt zur Verwendung über GraphQL ohne Anpassung der REST Builder-API
Gewährleistung der Konsistenz für Entwickler von Mobil- und SPA-Anwendungen.

Sie müssen nicht alle diese Funktionen verwenden, sondern nur diese Funktionen an der richtigen Stelle verwenden.

In diesem Artikel, der den Beginn der Blogserie markiert, zeigen wir Ihnen die Hauptteile der YAML-Datei, mit der ein Projekt zur Verwendung des neuen REST Builder eingerichtet und Einstiegspunkte definiert werden. Da dieser Artikel lang sein wird, werde ich ihn in mehrere Teile unterteilen, beginnend mit der Definition des Servicepfads (Einstiegspunkt) und der Erläuterung des Aufbaus des Service.

Vor der Arbeit

Bevor Sie beginnen, lesen Sie die offizielle Dokumentation von Liferay zur Verwendung von REST Builder (https://portal.liferay.dev/docs/7-2/appdev/-/knowledge_base/a/generating-apis-with-rest-). Bitte lesen Sie Builder). Das Lesen des Artikels dauert nicht lange. Kehren Sie daher nach dem Lesen zu diesem Artikel zurück.

Starten Sie das Projekt

Führen Sie den folgenden Befehl aus, um ein funktionierendes Projekt zu erstellen:

blade init -v 7.2 vitamins

Dieses Mal haben wir das Projekt "** Vitamin **" genannt, um uns die Struktur des Projekts leichter vorstellen zu können. Dieses Projekt besteht aus Vitaminen und Mineralien, die mehr Vitamine und Mineralien als Webinhalte enthalten müssen. Daher ist zusätzlich zur kopflosen REST-Schicht (REST Builder) eine benutzerdefinierte Service-Schicht (Service Builder) erforderlich.

Hinweis: Es wird davon ausgegangen, dass die Zielplattform von nun an in gradle.properties aktiviert ist. Wenn Sie es bereits eingestellt haben, lesen Sie problemlos weiter. Ich verwende die Zielplattform, daher füge ich die Version nicht in die Datei build.gradle ein. * *

Laden Sie dann das Projekt in die IDE und führen Sie die folgenden Schritte aus, um die Datei build.gradle mit dem Modul headless-vitamins-impl (siehe unten) zu bearbeiten: https://portal.liferay.dev/docs/7-2/reference / - / know_base / r / rest-builder-gradle-plugin

Hinweis: Wenn Sie Liferay Gradle Workspace verwenden, lautet das von diesem Arbeitsbereich generierte Build-Skript "build.gradle" im Modul "headress- -impl", was im Referenzartikel nicht angegeben ist. Es geht in die Datei, nicht in die Datei "settings.gradle" oder die Datei "build.gradle" auf Stammebene. Wenn Sie in diesem Fall versuchen, das Build-Skript in die Datei "settings.gradle" einzufügen, wird ein unerwarteter Fehler wie "org.gradle.initialization.DefaultSettings_Decorated" angezeigt, der nicht in "org.gradle.api.Project" umgewandelt werden kann. In diesem Fall bedeutet dies, dass Ihr REST Builder-Plug-In in einer falschen Datei aufgeführt ist. * *

Sie können überprüfen, ob REST Builder tatsächlich verfügbar ist, indem Sie den Befehl ./gradlew Tasks im Modul Headless-Vitamins-Impl ausführen:

$ ./gradlew tasks

> Task :tasks

------------------------------------------------------------
All tasks runnable from root project
------------------------------------------------------------

Build tasks
-----------
assemble - Assembles the outputs of this project.
build - Assembles and tests this project.
buildCSS - Build CSS files.
buildDependents - Assembles and tests this project and all projects that depend on it.
buildLang - Runs Liferay Lang Builder to translate language property files.
buildNeeded - Assembles and tests this project and all projects it depends on.
buildREST - Runs Liferay REST Builder.
...Kürzung...

Headless-Vitamins-API,Headless-Vitamine im Ordnermodules / Headless-Vitamins (ich habe dieses Unterverzeichnis erstellt, um die Headless-Module zusammenzusetzen) im Arbeitsbereich, da ich eine Reihe von Modulen benötige Erstellen Sie -impl, headless-vitamins-client und headless-vitamins-test. In der Referenzdokumentation wird das Erstellen dieser zusätzlichen Module nicht erwähnt, aber wie wir später sehen werden, werden sie benötigt.

$ cd modules/headless-vitamins
$ blade create -t api -v 7.2 -p com.dnebinger.headless.vitamins headless-vitamins-api
Successfully created project headless-vitamins-api in vitamins/modules/headless-vitamins
$ blade create -t api -v 7.2 -p com.dnebinger.headless.vitamins headless-vitamins-impl
Successfully created project headless-vitamins-impl in vitamins/modules/headless-vitamins
$ blade create -t api -v 7.2 -p com.dnebinger.headless.vitamins headless-vitamins-client
Successfully created project headless-vitamins-client in vitamins/modules/headless-vitamins
$ blade create -t api -v 7.2 -p com.dnebinger.headless.vitamins headless-vitamins-test
Successfully created project headless-vitamins-test in vitamins/modules/headless-vitamins

Da beim Erstellen eines Moduls mit dem obigen Befehl api als Typ angegeben wurde, werden auch einige unnötige Pakete und Java-Dateien generiert. Es wird einige Zeit dauern, diese zu bereinigen. Sie müssen auch das Verzeichnis "src / mai" des Verzeichnisses "headless-vitamins-test" in "src / testIntegration" umbenennen.

Für dieses Projekt generiert REST Builder einige Integrationstestfälle, für deren Funktion Sie jedoch das entsprechende Verzeichnis benötigen. Die Datei bnd.bnd wird mit den symbolischen Namen "com.dnebinger.headless.vitamins.api" und "com.dnebinger.headless.vitamins.impl" usw. aktualisiert, um den Standard-Namenskonventionen von Liferay für Bundles zu folgen. Die Datei "build.gradle" erfordert viele Ergänzungen, ist aber eine Verschnaufpause.

Service-Definition

Von hier aus wird es allmählich Spaß machen. Erstellen Sie eine YAML-Datei, um den Service-Endpunkt zu definieren. Wenn Sie dies zum ersten Mal tun, finden Sie es möglicherweise entmutigend.

Zunächst als einfache Aufgabe. Sie müssen die Datei rest-config.yamlinheadless-vitamins-impl` hinzufügen.

apiDir: "../headless-vitamins-api/src/main/java"
apiPackagePath: "com.dnebinger.headless.vitamins"
application:
    baseURI: "/headless-vitamins"
    className: "HeadlessVitaminsApplication"
    name: "dnebinger.Headless.Vitamins"
author: "Dave Nebinger"
clientDir: "../headless-vitamins-client/src/main/java"
testDir: "../headless-vitamins-test/src/testIntegration/java"

Dies ist eine Sammlung der Elemente, die Sie erstellt haben, damit Liferays kopflose Arbeit funktioniert. Die letzten beiden Einträge beziehen sich auf den Client und den Test. Daher sollte diese Arbeit zuerst durchgeführt werden.

Als nächstes werden wir mit der Datei rest-openapi.yaml arbeiten. Diese Datei wird auch im Modul "Headless-Vitamins-Impl" erstellt. Anstatt alles auf einmal wegzuwerfen, finden Sie hier ein schrittweises Verständnis der Details. Alle Dateistrukturen finden Sie in diesem Repository (https://github.com/dnebing/vitamins).

Jede OpenAPI YAML-Datei besteht aus drei Abschnitten: ** Meta **, ** Pfade ** (Endpunkte) und ** Wiederverwendbare Komponenten ** (Typdefinitionen) und unterscheidet sich nicht von der diesmal erstellten.

Mein Meta-Bereich ist:

openapi: 3.0.1
info:
  title: "Headless Vitamins"
  version: v1.0
  description: "API for accessing Vitamin details."

Bisher machen wir gute Fortschritte.

Hinweis: Einfache Texteditoren eignen sich nicht zum Bearbeiten von YAML-Dateien. Insbesondere gibt es Schwierigkeiten beim richtigen Einrücken beim Umwickeln von Linien. Wenn Sie keinen vertrauten Editor haben, wird das Gliederungstool von Swagger unter https://editor.swagger.io/ empfohlen. Dieses Tool verfügt nicht nur über eine ordnungsgemäße Einrückung, sondern auch über eine Code-Vervollständigung, die bei der Arbeit mit Dateien im OpenAPI-YAML-Format sehr nützlich ist. * *

Typdefinition

Geben Sie als Nächstes die wiederverwendbare Komponente frei, die Sie gerade erstellt haben. Diese funktionieren nicht von alleine, aber sie erleichtern die spätere Abdeckung von Pfaden.

Mein Haupttyp und "Vitamin" -Typ:

components:
  schemas:
    Vitamin:
      description: Contains all of the data for a single vitamin or mineral.
      properties:
        name:
          description: The vitamin or mineral name.
          type: string
        id:
          description: The vitamin or mineral internal ID.
          type: string
        chemicalNames:
          description: The chemical names of the vitamin or mineral if it has some.
          items:
            type: string
          type: array
        properties:
          description: The chemical properties of the vitamin or mineral if it has some.
          items:
            type: string
          type: array
        group:
          description: The group the vitamin or mineral belongs to, i.e. the B group or A group.
          type: string
        description:
          description: The description of the vitamin or mineral.
          type: string
        articleId:
          description: A journal articleId if there is a web content article for this vitamin.
          type: string
        type:
          description: The type of the vitamin or mineral.
          enum: [Vitamin, Mineral, Other]
          type: string
        attributes:
          description: Health properties attributed to the vitamin or mineral.
          items:
            type: string
          type: array
        risks:
          description: Risks associated with the vitamin or mineral.
          items:
            type: string
          type: array
        symptoms:
          description: Symptoms associated with the vitamin or mineral deficiency.
          items:
            type: string
          type: array
        creator:
          $ref: "#/components/schemas/Creator"
      type: object

Das obige ist das YAML-Format. Einrückungen stellen Hierarchien dar, wobei Reihen tieferer Einrückungen ihre untergeordneten Elemente sind und Reihen derselben Hierarchie Geschwister bedeuten.

Der "Vitamin" -Typ hat viele Eigenschaften. Die Eigenschaften reichen von einfachen wie Name und ID bis zu komplexeren. Die type-Eigenschaft ist String, wird jedoch durch die Aufzählung möglicher Werte begrenzt. Der Ersteller ist ein Verweis auf ein anderes Objekt ($ ref ist dies) in dieser Datei.

Wenn sich in derselben Datei ein "$ ref" befindet, müssen Sie eine Referenz angeben. Die Erstellerarten von "Vitaminen", die aus Liferays "Headless-Delivery" -Datei kopiert wurden, sind:

    Creator:
      description: Represents the user account of the content's creator/author. Properties follow the [creator](https://schema.org/creator) specification.
      properties:
        additionalName:
          description: The author's additional name (e.g., middle name).
          readOnly: true
          type: string
        familyName:
          description: The author's surname.
          readOnly: true
          type: string
        givenName:
          description: The author's first name.
          readOnly: true
          type: string
        id:
          description: The author's ID.
          format: int64
          readOnly: true
          type: integer
        image:
          description: A relative URL to the author's profile image.
          format: uri
          readOnly: true
          type: string
        name:
          description: The author's full name.
          readOnly: true
          type: string
        profileURL:
          description: A relative URL to the author's user profile.
          format: uri
          readOnly: true
          type: string
      type: object

Das ist alles für die Typbeschreibung.

Zusammenfassung

Ist es zu früh zum Zusammenstellen? Sicher ist die Arbeit noch unvollständig! Seien Sie versichert, dass der nächste Teil bereits veröffentlicht wurde.

In diesem Teil haben wir Ihnen gezeigt, wie Sie einen neuen Liferay Gradle-Arbeitsbereich mit benutzerdefinierten Headless-Diensten und den erforderlichen Modulen erstellen. Wir haben auch den Abschnitt Pfad übersprungen und den Abschnitt Meta berührt, um das Projekt "Vitamin" und die Erstellerobjekte zu definieren, um die wiederverwendbaren Komponenten, einschließlich der OpenAPI YAML-Datei, besser zu verstehen.

Nächstes Mal identifiziert Pfade (Einstiegspunkte) Wir sehen uns im nächsten Teil!

https://github.com/dnebing/vitamins