Hono OpenAPI 소개: HonoJS용 API 문서 단순화

먼저: Hono용 OpenAPI 라이브러리가 이미 존재하는데 왜 또 다른 OpenAPI 라이브러리를 만드는가?

많은 분들이 물어보시는 질문입니다. 예, Yusuke가 만든 Zod OpenAPI가 있습니다. 훌륭한 패키지이지만 새로운 솔루션을 만들게 된 몇 가지 중요한 제한 사항이 있습니다.

@hono/zod-openapi의 과제

두 가지 접근 방식을 비교하여 hono-openapi를 구축한 이유를 분석해 보겠습니다.

1. 구문 및 작업 흐름 차이점

@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',
  },
});

이제 이것을 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' },
      ],
    },
  })
);

차이점은 분명합니다. hono-openapi를 사용하면 표준 HonoJS 워크플로 내에서 직접 작업할 수 있습니다. 이렇게 하면 가파른 학습 곡선이 제거되고 구문이 HonoJS 문서 및 규칙에 맞게 정렬됩니다.

2. 옵트인 관련 과제

@hono/zod-openapi를 사용하면 기존 HonoJS 애플리케이션을 개조하여 OpenAPI 사양을 생성하는 것은 중요한 과제입니다. 대규모 애플리케이션의 경로를 다시 작성하는 것은 시간이 많이 걸리고 오류가 발생하기 쉽습니다. hono-openapi는 미들웨어로 작동하여 이를 해결하므로 큰 변경 없이 기존 앱에 추가할 수 있습니다.

3. 제한된 검증인 지원

원래 라이브러리는 Zod만 지원합니다. Zod는 훌륭하지만 많은 개발자는 Valibot, ArkType 및 TypeBox와 같은 대안을 사용합니다. hono-openapi는 유효성 검사기에 구애받지 않으며 여러 라이브러리에 대한 최고 수준의 지원을 제공합니다.

---

OpenAPI 사양이 중요한 이유

어떤 사람들은 "왜 OpenAPI 사양에 신경을 쓰는가?"라고 궁금해할 수도 있습니다. 내 앱은 그것들 없이도 잘 작동합니다.”

OpenAPI 사양 생성이 판도를 바꾸는 이유는 다음과 같습니다.

1. API 클라이언트 생성: 사양을 사용하여 다양한 프로그래밍 언어에 대한 클라이언트를 자동 생성하여 개발 시간을 절약합니다.
2. 개발자 협업: 최신 API 문서와 팀의 동기화를 유지하여 잘못된 의사소통과 버그를 줄입니다.
3. 간소한 디버깅: 모든 엔드포인트에 대해 명확하고 정확한 문서를 제공하여 API가 실패할 때 추측을 제거합니다.
4. 모범 사례: 코드베이스에 따라 발전하는 문서를 자동으로 생성하여 분기와 버전 전반에 걸쳐 일관성을 보장합니다.

프런트엔드와 백엔드 개발자가 API 세부정보를 수동으로 동기화해야 하는 팀에서 일해 본 적이 있다면 그것이 얼마나 고통스러운지 아실 것입니다. OpenAPI 사양은 단일 정보 소스를 제공하여 이 문제를 해결합니다.

---

hono-openapi를 선택하는 이유는 무엇입니까?

이러한 과제를 해결하고 모범 사례를 장려하기 위해 hono-openapi는 다음 목표를 염두에 두고 구축되었습니다.

• 검증기 독립적: 선호하는 검증 라이브러리(Zod, Typebox, ArkType, Valibot 등)를 사용하세요.
• 원활한 통합: 최소한의 변경으로 모든 HonoJS 프로젝트에 미들웨어로 추가하세요.
• 자동 OpenAPI 생성: 스키마를 한 번 정의하고 나머지는 라이브러리가 처리하도록 하세요.
• 유형 안전: 안정적이고 일관된 유형 검증을 위해 TypeScript로 구축되었습니다.
• 사용자 정의 가능: 생성된 OpenAPI 사양을 프로젝트 요구 사항에 맞게 조정합니다.

---

시작할 준비가 되셨나요?

이것이 여러분이 기다려오던 솔루션처럼 들린다면 라이브러리를 확인하고 대화에 참여하십시오.

• GitHub 저장소: hono-openapi
• 문서: GitHub README | 호노 예

---

이 기사를 통해 hono-openapi를 사용해 보고 이것이 API 구축 및 문서화를 어떻게 단순화하는지 확인하시기 바랍니다. 귀하의 피드백은 중요합니다! 더욱 강력한 HonoJS 커뮤니티를 함께 만들어 갑시다.

위 내용은 Hono OpenAPI 소개: HonoJS용 API 문서 단순화의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!