Memperkenalkan Hono OpenAPI: Memudahkan Dokumentasi API untuk HonoJS

Perkara pertama dahulu: mengapa perlu mencipta pustaka OpenAPI lain untuk Hono apabila satu sudah wujud?

Ini adalah soalan yang ditanya ramai. Ya, terdapat Zod OpenAPI, dicipta oleh Yusuke. Walaupun ia merupakan pakej yang hebat, ia mempunyai beberapa had ketara yang membawa kepada penciptaan penyelesaian baharu.

Cabaran bersama @hono/zod-openapi

Mari kita pecahkan mengapa hono-openapi dibina dengan membandingkan kedua-dua pendekatan.

1. Perbezaan Sintaks dan Aliran Kerja

Berikut ialah contoh menggunakan @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',
  },
});

Sekarang bandingkan ini dengan aplikasi yang sama yang ditulis dengan 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' },
      ],
    },
  })
);

Perbezaannya jelas: hono-openapi membolehkan anda bekerja terus dalam aliran kerja HonoJS standard. Ini menghapuskan keluk pembelajaran yang curam dan memastikan sintaks sejajar dengan dokumentasi dan konvensyen HonoJS.

2. Cabaran dengan Ikut serta

Dengan @hono/zod-openapi, mengubah suai aplikasi HonoJS sedia ada untuk menjana spesifikasi OpenAPI merupakan satu cabaran yang ketara. Menulis semula laluan untuk aplikasi yang besar boleh memakan masa dan terdedah kepada ralat. hono-openapi menyelesaikannya dengan bekerja sebagai perisian tengah, jadi anda boleh menambahkannya pada apl sedia ada tanpa perubahan besar.

3. Sokongan Pengesah Terhad

Pustaka asal hanya menyokong Zod. Walaupun Zod sangat baik, banyak pembangun menggunakan alternatif seperti Valibot, ArkType dan TypeBox. hono-openapi ialah validator-agnostik, menawarkan sokongan kelas pertama untuk berbilang perpustakaan.

---

Mengapa Spesifikasi OpenAPI Penting

Sesetengah mungkin tertanya-tanya, “Mengapa perlu bersusah payah dengan spesifikasi OpenAPI sama sekali? Apl saya berfungsi dengan baik tanpanya.”

Inilah sebabnya menjana spesifikasi OpenAPI adalah pengubah permainan:

1. Penjanaan Pelanggan API: Gunakan spesifikasi untuk menjana pelanggan secara automatik untuk pelbagai bahasa pengaturcaraan, menjimatkan masa pembangunan.
2. Kerjasama Pembangun: Pastikan pasukan anda segerak dengan dokumentasi API terkini, mengurangkan miskomunikasi dan pepijat.
3. Penyahpepijatan Terselaras: Hapuskan tekaan apabila API gagal dengan menyediakan dokumentasi yang jelas dan tepat untuk semua titik akhir.
4. Amalan Terbaik: Menjana dokumentasi secara automatik yang berkembang dengan pangkalan kod anda, memastikan konsistensi merentas cawangan dan versi.

Jika anda pernah bekerja dalam pasukan di mana pembangun bahagian hadapan dan belakang perlu menyegerakkan butiran API secara manual, anda akan tahu betapa peritnya perkara itu. Spesifikasi OpenAPI menyelesaikannya dengan menyediakan satu sumber kebenaran.

---

Mengapa Memilih hono-openapi?

Untuk menangani cabaran ini dan menggalakkan amalan terbaik, hono-openapi telah dibina dengan matlamat berikut:

• Validator-Agnostik: Gunakan pustaka pengesahan pilihan anda — Zod, Typebox, ArkType, Valibot atau lain-lain.
• Penyatuan Lancar: Tambahkannya pada mana-mana projek HonoJS sebagai perisian tengah, dengan perubahan yang minimum.
• Penjanaan OpenAPI Automatik: Tentukan skema sekali dan biarkan perpustakaan mengendalikan yang lain.
• Selamat Jenis: Dibina dengan TypeScript untuk pengesahan jenis yang boleh dipercayai dan konsisten.
• Boleh disesuaikan: Sesuaikan spesifikasi OpenAPI yang dijana untuk memenuhi keperluan projek anda.

---

Bersedia untuk Bermula?

Jika ini kelihatan seperti penyelesaian yang anda tunggu-tunggu, lihat perpustakaan dan sertai perbualan:

• Repositori GitHub: hono-openapi
• Dokumentasi: GitHub README | Contoh Hono

---

Saya harap artikel ini meyakinkan anda untuk mencuba hono-openapi dan melihat cara ia memudahkan membina dan mendokumentasikan API. Maklum balas anda penting! Mari kita bina komuniti HonoJS yang lebih kukuh bersama-sama.

Atas ialah kandungan terperinci Memperkenalkan Hono OpenAPI: Memudahkan Dokumentasi API untuk HonoJS. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!