Présentation de Hono OpenAPI : simplifier la documentation de l'API pour HonoJS

Tout d'abord : pourquoi créer une autre bibliothèque OpenAPI pour Hono alors qu'il en existe déjà une ?

C'est une question que beaucoup se sont posée. Oui, il existe Zod OpenAPI, créé par Yusuke. Bien qu'il s'agisse d'un excellent package, il présente certaines limitations importantes qui ont conduit à la création d'une nouvelle solution.

Les défis avec @hono/zod-openapi

Décomposons pourquoi l'hono-openapi a été construit en comparant les deux approches.

1. Différences de syntaxe et de flux de travail

Voici un exemple utilisant @hono/zod-openapi :

// Using @hono/zod-openapi 
import { OpenAPIHono, createRoute, z } from '@hono/zod-openapi';

const ParamsSchema = z.object({
  id: z
    .string()
    .min(3)
    .openapi({
      param: {
        name: 'id',
        in: 'path',
      },
      example: '1212121',
    }),
});

const route = createRoute({
  method: 'get',
  path: '/users/{id}',
  request: {
    params: ParamsSchema,
  },
});

const app = new OpenAPIHono();

app.openapi(route, (c) => {
  const { id } = c.req.valid('param');
  return c.json({ id, age: 20, name: 'Ultra-man' });
});

// The OpenAPI documentation will be available at /doc
app.doc('/doc', {
  openapi: '3.0.0',
  info: {
    version: '1.0.0',
    title: 'My API',
  },
});

Comparez maintenant cela à la même application écrite avec hono-openapi :

// Using Hono-OpenAPI
import z from 'zod';
import { Hono } from 'hono';
import { describeRoute } from 'hono-openapi';
import { resolver, validator as zValidator } from 'hono-openapi/zod';

// Extending the Zod schema with OpenAPI properties
import 'zod-openapi/extend';

const paramSchema = z.object({
  id: z.string().min(3).openapi({ example: '1212121' }),
});

const app = new Hono();

app.get(
  '/',
  zValidator('param', paramSchema),
  (c) => {
    const param = c.req.valid('param');
    return c.text(`Hello ${param?.id}!`);
  }
);

app.get(
  '/openapi',
  openAPISpecs(app, {
    documentation: {
      info: {
        title: 'Hono',
        version: '1.0.0',
        description: 'API for greeting users',
      },
      servers: [
        { url: 'http://localhost:3000', description: 'Local server' },
      ],
    },
  })
);

La différence est claire : hono-openapi vous permet de travailler directement dans le workflow HonoJS standard. Cela élimine la courbe d'apprentissage abrupte et garantit que la syntaxe est conforme à la documentation et aux conventions HonoJS.

2. Défis liés à l'adhésion

Avec @hono/zod-openapi, la mise à niveau d'une application HonoJS existante pour générer des spécifications OpenAPI est un défi de taille. La réécriture des routes pour une application volumineuse peut prendre du temps et être sujette aux erreurs. hono-openapi résout ce problème en fonctionnant comme middleware, vous pouvez donc l'ajouter aux applications existantes sans changements majeurs.

3. Prise en charge limitée du validateur

La bibliothèque originale ne prend en charge que Zod. Bien que Zod soit excellent, de nombreux développeurs utilisent des alternatives comme Valibot, ArkType et TypeBox. hono-openapi est indépendant du validateur, offrant une prise en charge de première classe pour plusieurs bibliothèques.

---

Pourquoi les spécifications OpenAPI sont importantes

Certains pourraient se demander : « Pourquoi s'embêter avec les spécifications OpenAPI ? Mon application fonctionne bien sans eux. »

Voici pourquoi la génération de spécifications OpenAPI change la donne :

1. Génération de clients API : utilisez les spécifications pour générer automatiquement des clients pour différents langages de programmation, économisant ainsi du temps de développement.
2. Collaboration avec les développeurs : gardez votre équipe synchronisée avec une documentation API à jour, réduisant ainsi les problèmes de communication et les bugs.
3. Débogage simplifié : éliminez les incertitudes en cas d'échec des API en fournissant une documentation claire et précise pour tous les points de terminaison.
4. Bonnes pratiques : générez automatiquement une documentation qui évolue avec votre base de code, garantissant ainsi la cohérence entre les branches et les versions.

Si vous avez déjà travaillé dans une équipe où les développeurs front-end et back-end devaient synchroniser manuellement les détails de l'API, vous saurez à quel point cela peut être pénible. Les spécifications OpenAPI résolvent ce problème en fournissant une source unique de vérité.

---

Pourquoi choisir Hono-Openapi ?

Pour relever ces défis et promouvoir les meilleures pratiques, hono-openapi a été construit avec les objectifs suivants en tête :

• Validator-Agnostic : utilisez votre bibliothèque de validation préférée : Zod, Typebox, ArkType, Valibot ou autres.
• Intégration transparente : ajoutez-le à n'importe quel projet HonoJS en tant que middleware, avec des modifications minimes.
• Génération automatique OpenAPI : définissez les schémas une fois et laissez la bibliothèque gérer le reste.
• Type-Safe : construit avec TypeScript pour une validation de type fiable et cohérente.
• Personnalisable : adaptez les spécifications OpenAPI générées pour répondre aux exigences de votre projet.

---

Prêt à commencer ?

Si cela ressemble à la solution que vous attendiez, consultez la bibliothèque et rejoignez la conversation :

• Référentiel GitHub : hono-openapi
• Documentation : GitHub README | Exemples d'honneur

---

J'espère que cet article vous convaincra d'essayer hono-openapi et de voir comment il simplifie la création et la documentation des API. Vos commentaires comptent ! Construisons ensemble une communauté HonoJS plus forte.

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!