Cet article a été publié sur Liferay Community Blog, _ Creating Headless APIs (Part 1) Ceci est une traduction de -headless-apis-part-1) _.

introduction

Récemment, j'ai expérimenté la nouvelle API sans tête de Liferay. Plus précisément, il s'agit d'un SAP basé sur React qui utilise des modules de livraison sans tête et de gestion des utilisateurs sans tête. Nous couvrirons l'implémentation quatre fois, mais cette fois, nous vous montrerons comment utiliser les outils REST Builder pour créer votre propre API headless.

Vous pouvez avoir les questions suivantes ici.

"_Pourquoi utiliser REST Builder au lieu de votre propre REST basé sur JAX-RS traditionnel? _"

Le REST Builder de Liferay fait plus que simplement créer des applications qui exposent des points de terminaison. Il fournit également les fonctionnalités supplémentaires suivantes: :

--Intégration avec le pipeline de certification de Liferay --Intégration avec la gestion de CORS par Liferay

Facilité sans tête pour prendre en charge l'intégration avec la recherche Liferay, le filtrage, la pagination et plus --Fonction de génération JSON ou XML pour la demande de l'appelant
Intégration avec le prochain point de terminaison Liferay GraphQL pour une utilisation via GraphQL sans personnaliser l'API REST Builder
Assurer la cohérence pour les développeurs d'applications mobiles et SPA.

Vous n'êtes pas obligé d'utiliser tout cela, utilisez simplement ces fonctionnalités au bon endroit.

Dans cet article, le premier d'une série de blogs, nous vous montrerons les principales parties du fichier YAML qui configure un projet pour utiliser le nouveau REST Builder et définit les points d'entrée. Comme cet article sera long, je vais le diviser en plusieurs parties, en commençant par la définition du chemin du service (point d'entrée) et en expliquant la construction du service.

Pré-travail

Avant de commencer, la documentation officielle de Liferay sur la façon d'utiliser REST Builder (https://portal.liferay.dev/docs/7-2/appdev/-/knowledge_base/a/generating-apis-with-rest- Veuillez lire le constructeur). La lecture de l'article ne prend pas longtemps, alors revenez sur cet article après l'avoir lu.

Démarrez le projet

Exécutez la commande suivante pour créer un projet de travail:

blade init -v 7.2 vitamins

Cette fois, nous avons baptisé le projet «** Vitamin **» pour faciliter l'imagination de la structure du projet. Ce projet se compose de vitamines et de minéraux, qui doivent contenir plus de vitamines et de minéraux que le contenu Web. Par conséquent, une couche de service personnalisée (Service Builder) est requise en plus de la couche REST headless (REST Builder).

Remarque: il est supposé que la plate-forme cible est désormais activée dans gradle.properties. Si vous l'avez déjà défini, poursuivez votre lecture sans problème. J'utilise la plate-forme cible, donc je n'inclus pas la version dans le fichier build.gradle. *

Chargez ensuite le projet dans l'EDI et suivez ces étapes pour éditer le fichier build.gradle avec le module headless-vitamins-impl (discuté ci-dessous): https://portal.liferay.dev/docs/7-2/reference / - / base_connaissance / r / rest-builder-gradle-plugin

Remarque: Notez que si vous utilisez Liferay Gradle Workspace, le script de construction généré par cet espace de travail est build.gradle dans le module headress- <nom> -impl, comme une mise en garde non spécifiée dans l'article de référence. Il va dans le fichier, pas le fichier settings.gradle ou le fichier de niveau racine build.gradle. Dans ce cas, si vous essayez de placer le script de construction dans le fichier settings.gradle, vous obtiendrez une erreur inattendue telle que ʻorg.gradle.initialization.DefaultSettings_Decorated ne peut pas être converti en org.gradle.api.Project`. Si cela se produit, cela signifie que votre plug-in REST Builder est répertorié dans un fichier incorrect. *

Vous pouvez vérifier que REST Builder est réellement disponible en exécutant la commande ./gradlew tasks dans le module headless-vitamins-impl:

$ ./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.
...réduction...

Headless-vitamins-api,headless-vitamins dans le dossiermodules / headless-vitamins` de l'espace de travail (j'ai créé ce sous-répertoire pour assembler les modules headless) Créez -impl »,« headless-vitamins-client »et« headless-vitamins-test ». La documentation de référence ne mentionne pas la création de ces modules supplémentaires, mais comme nous le verrons plus tard, ils seront nécessaires.

$ 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

Puisque ʻapia été spécifié comme type lors de la création d'un module avec la commande ci-dessus, certains packages et fichiers java inutiles sont également générés. Il faudra un certain temps pour les nettoyer. Vous devez également renommer le répertoiresrc / mai du répertoire headless-vitamins-test en src / testIntegration`.

Pour ce projet, REST Builder générera des cas de test d'intégration, mais vous avez besoin du répertoire approprié pour qu'ils fonctionnent. Le fichier bnd.bnd est mis à jour avec les noms symboliques «com.dnebinger.headless.vitamins.api» et «com.dnebinger.headless.vitamins.impl», etc. pour suivre les conventions de dénomination standard des bundles Liferay. Le fichier build.gradle nécessitera beaucoup d'ajouts, mais c'est un répit.

Définition du service

De là, cela deviendra progressivement amusant. Créons un fichier YAML pour définir le point de terminaison du service. Si c'est la première fois que vous faites cela, vous pouvez trouver cela décourageant.

Tout d'abord, comme une tâche simple. Vous devez ajouter le fichier rest-config.yamldansheadless-vitamins-impl`.

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"

Il s'agit d'une collection d'éléments que vous avez créés dont le headless de Liferay a besoin pour fonctionner. Les deux dernières entrées font référence au client et au test. Par conséquent, ce travail doit être effectué en premier.

Ensuite, nous travaillerons avec le fichier rest-openapi.yaml. Ce fichier est également créé dans le module headless-vitamins-impl. Plutôt que de tout jeter à la fois, voici une compréhension étape par étape des détails. Toutes les structures de fichiers peuvent être trouvées dans ce référentiel (https://github.com/dnebing/vitamins).

Chaque fichier OpenAPI YAML se compose de trois sections, ** Meta **, ** Paths ** (points de terminaison) et ** Composants réutilisables ** (définitions de type), et n'est pas différent de celui créé cette fois.

Ma section méta est:

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

Nous faisons de bons progrès jusqu'à présent.

Remarque: les éditeurs de texte simples ne conviennent pas à l'édition de fichiers YAML. En particulier, il y a des difficultés avec une indentation correcte lors de l'enroulement des lignes. Si vous n'avez pas d'éditeur familier, l'outil de présentation de Swagger disponible sur https://editor.swagger.io/ est recommandé. Cet outil a non seulement une mise en retrait appropriée, mais également une complétion de code qui est très utile lorsque vous travaillez avec des fichiers au format OpenAPI YAML. *

Définition du type

Ensuite, partagez le composant réutilisable que vous venez de créer. Ceux-ci ne fonctionnent pas seuls, mais ils allègent le fardeau de couvrir les chemins plus tard.

Mon type principal et type "vitamine":

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

Ce qui précède est le format YAML. Les retraits représentent des hiérarchies, les lignes de retraits plus profonds étant leurs enfants et les lignes de la même hiérarchie signifiant frères et sœurs.

Le type «vitamine» a de nombreuses propriétés. Les propriétés vont des plus simples telles que le nom et l'identifiant aux plus complexes. La propriété type est «String», mais elle est limitée par l'énumération des valeurs possibles. Le créateur est une référence à un autre objet («$ ref» est ceci) dans ce fichier.

S'il y a un $ ref dans le même fichier, cela signifie que vous devez inclure une référence. Les types de créateurs de "vitamines" copiés à partir du fichier "headless-delivery" de Liferay sont:

    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

C'est tout pour la description du type.

Résumé

Est-il trop tôt pour mettre en place? Certes, le travail est encore incomplet! Soyez assuré que la partie suivante a déjà été publiée.

Dans cette partie, nous vous avons montré comment créer un nouvel espace de travail Liferay Gradle avec des services sans tête personnalisés et les modules requis. J'ai également ignoré la section Path et touché la section Meta pour définir un projet "vitamin" et des objets de créateur pour mieux comprendre les composants réutilisables, y compris le fichier OpenAPI YAML.

La prochaine fois identifiera les chemins (points d'entrée) Rendez-vous dans la prochaine partie!

https://github.com/dnebing/vitamins