API Next.js, interface utilisateur Swagger et spécification OpenAPI

L’API REST est reine lorsqu’il s’agit d’écrire une logique côté serveur et de fournir des données côté client. Au fur et à mesure que votre équipe et votre solution évoluent, le flux de travail de documentation de l’API de votre équipe nécessitera une stratégie pour maintenir une documentation claire et de haut niveau. Ma recommandation est d’utiliser la spécification OpenAPI et Swagger.

OpenAPI Specification (OSA) est une norme d’écriture de documentation d’API. Swagger est une plate-forme intégrée de conception et de documentation d’API.

Cet article se concentrera sur l’exploitation de la puissance de la norme OSA et de l’interface utilisateur Swagger lors du développement de vos itinéraires d’API Next.js. Je discuterai des avantages de documenter vos itinéraires d’API Next.js vers les spécifications OpenAPI et des avantages de tirer parti de votre spécification OpenAPI avec Swagger. Je vais également vous apprendre à générer une spécification OpenAPI à partir de votre implémentation d’API Next.js et à héberger votre spécification OpenAPI dans Swagger avec des exemples d’une application Next.js réelle.

Avantages de documenter vos itinéraires d’API Next.js avec Spécifications OpenAPI (OAS 3.0):

• Une spécification OpenAPI peut être utile pour générer des affichages visuels de votre service APIgénérer du code côté client et côté serveur pour interagir avec votre API ou intégrer des outils de test.

Avantages de tirer parti de votre spécification OpenAPI à l’aide de Swagger :

• Test d’API piloté par l’interface utilisateur
• Les personnes non techniques peuvent voir les avantages et le but de votre API à un niveau élevé
• La documentation peut aider à acclimater les nouveaux membres de l’équipe à votre solution

Comment créer votre spécification OpenAPI avec la dépendance next-swagger-doc :

• Je recommande d’utiliser prochain-swagger-doc pour générer votre spécification OpenAPI
• En utilisant cette dépendance, vous pouvez soit créer nativement votre documentation Swagger, soit générer votre spécification OpenAPI sur une page, soit générer un fichier .json via la CLI.
• Vous pouvez suivre votre méthode préférée via le guide d’implémentation de la dépendance ici : https://www.npmjs.com/package/next-swagger-doc

• prochain-swagger-doc la méthode #3 générera votre spécification OpenAPI à partir des commentaires de vos routes Next.js.

  • C’est ma méthode préférée car elle offre le plus de personnalisation à votre documentation. Je vais expliquer comment rédiger les commentaires de l’OEA requis pour utiliser la méthode #3 dans cette section. Tu peux sautez cette section si vous préférez utiliser la méthode #1 ou #3 du guide de mise en œuvre.

  • J’écrirai mes commentaires avec YAML aux normes OAS 3.0. Il est également possible d’écrire vos commentaires au format JSON.

• Schémas de construction

  • Un schéma dans ce contexte est un moyen de mapper des modèles d’objets à vos itinéraires.
  • Disons que nous définissons un objet pour une brasserie.

• Construire des itinéraires

  • • OBTENIR
    • PUBLIER
      • Construisons un commentaire de requête POST pour générer une route Swagger.
      • Nous allons continuer avec notre exemple BreweryObject. Nous enverrons une requête POST à ​​un BreweryObject particulier en fonction de son nom. Pour cette requête, nous utiliserons un attribut « breweryName » dans le corps de la requête pour déterminer l’enregistrement à recevoir.

        • /** 
           * @swagger
           *  /api/Firebase/Endpoints/GetBreweryByName:
           *    post:
           *      summary: Get Brewery by Name
           *      description: Get a Brewery object by name.
           *      requestBody:
           *        content:
           *          application/json:
           *            schema:
           *              breweryName: string
           *            example:
           *              breweryName: Creature Comforts Brewing Company
           *      responses:
           *        '200':
           *          description: OK
           *          content: 
           *            application/json:
           *              schema:
           *                $ref: '#/components/schemas/BreweryObject'
          */
          const handler = async (
            req: NextApiRequest,
            res: NextApiResponse<BreweryObject>
          ) => {
            ...
          } 
          export default handler;

      • Visuellement, dans Swagger, cela se traduira par…
        • 
    • EFFACER
    • METTRE À JOUR

Comment tirer parti de votre spécification OpenAPI dans Swagger

• Si vous avez choisi la méthode n ° 1 pour implémenter next-swagger-docs avec swagger-ui-react, cette pièce est déjà faite pour vous. Visitez la page swagger en direct que vous avez créée et vous devriez voir votre interface utilisateur Swagger.
• Sinon, vous devrez héberger votre API sur SwaggerHub. Une fois que vous y avez créé un compte, créez une nouvelle API.

  • Si vous avez suivi ce guide, vous avez très probablement utilisé la méthode n°2 pour implémenter next-swagger-docs. Accédez à la route de documentation next-swagger-doc que vous avez spécifiée, puis copiez et collez le contenu de la page dans votre éditeur de documentation de l’API SwaggerHub.

    • Notez que si vous souhaitez ajouter des serveurs d’hébergement à votre configuration d’API, vous pouvez le faire sous la forme d’un tableau d’objets, chacun avec un attribut url.

    • 
  • Si vous avez choisi la méthode n°3 pour implémenter next-swagger-docs avec next-swagger-doc-cli, utilisez la CLI pour générer votre fichier .json. Copiez et collez le contenu du fichier .json dans votre éditeur de documentation de l’API SwaggerHub.

Épilogue

• Les images de logo utilisées sont protégées par le Creative Commons :