OpenAPI Semantic Generator (@dotflash/openapi-semantic-generator)

English | 한국어

English

Middleware tool that analyzes code generated by OpenAPI Generator and automatically creates semantic matching documents (llms.txt: A unified index mapping API intents, operationId, HTTP paths, and actual TypeScript source file locations; agent.md: A semantic guide explaining how to interpret llms.txt.) optimized for LLM agents.

💡 Best Practices for AI Agents

To maximize the effectiveness of this tool, reference the generated files in your AI configuration files (e.g., .cursorrules, claude.md, copilot-instructions.md).

Example: .cursorrules or claude.md

# API Usage Guidelines

Always refer to the following files to understand available APIs and their usage:

- [API Index](openapi/llms.txt)
- [Agent Guide](openapi/agent.md)

1. Search `llms.txt` for the desired operation.
2. Read the implementation in the "Source File" path.
3. Call the API as defined in the source code.

It provides an index and guide that allows LLMs to understand large-scale API code (even 2,500+ lines) at a glance, maximizing agent code comprehension.

Key Features

• Middleware Mode: Analyzes already generated code folders and compares them with OpenAPI specs.
• Smart Path Mapping: Automatically detects actual file locations within generated code (e.g., typescript-axios).
• URL Support: Supports direct input from remote OpenAPI JSON/YAML URLs in addition to local files.
• Agent Optimized: Provides LLM-exclusive summaries (llms.txt) and interaction guides (agent.md).

Installation

npm install -g @dotflash/openapi-semantic-generator

Usage

npx openapi-semantic-generator <spec-url-or-path> -o <generated-code-dir> [options]

Required Arguments

1. <spec>: Path or URL to the OpenAPI spec file (e.g., https://.../openapi.json)

Options

• -o, --output <dir>: Required. Directory where the generated code is located. This tool will scan this directory to find API files.

  • Example: ./src/api, ./generated/client
  • Important: The generated TypeScript files must be inside this directory or its subdirectories.

• --api-dir <path>: Optional. Relative path from the output directory where API files are located.

  • Example: services, api, client/apis
  • This path is relative to the -o directory, not the current working directory.
  • If not specified, the tool searches in api/, apis/, and the output directory itself (in that order).

Usage Examples

# Basic usage: API files are in ./src/api/
npx openapi-semantic-generator spec.yaml -o ./src/api

# API files are in ./generated/services/
npx openapi-semantic-generator spec.yaml -o ./generated --api-dir services

# Using a remote spec URL
npx openapi-semantic-generator https://api.example.com/openapi.json -o ./src/api

# API files are directly in the output directory
npx openapi-semantic-generator spec.yaml -o ./dist/client

Generated Documents

Two core documents are generated to help agents understand the API structure with minimal tokens and start implementation immediately.

1. llms.txt (Semantic Index):

   • A unified index mapping API intents, operationId, HTTP paths, and actual TypeScript source file locations.
   • Agents can see at a glance what functionality to use and which files to read to check types.

2. agent.md (Agent Interaction Guide):

   • Provides guidelines on how the agent should utilize this package.
   • Defines procedures for searching via llms.txt and implementing by referencing source code.

한국어

OpenAPI Generator로 생성된 코드들을 분석하여 LLM 에이전트가 활용하기 좋은 시맨틱 매칭 문서(llms.txt, agent.md)를 자동으로 생성해주는 미들웨어 도구입니다.

2,500라인이 넘는 대규모 API 코드라도 LLM이 한눈에 파악할 수 있는 인덱스와 가이드를 제공하여 에이전트의 코드 이해도를 극대화합니다.

핵심 기능

• Middleware Mode: 이미 생성된 코드 폴더와 OpenAPI 스펙을 비교 분석하여 문서 생성.
• Smart Path Mapping: typescript-axios 등 생성된 코드 내의 실제 파일 위치 자동 탐색.
• URL Support: 로컬 파일뿐만 아니라 원격 OpenAPI JSON/YAML URL 직접 지원.
• Agent Optimized: LLM 전용 요약(llms.txt) 및 상세 가이드(agent.md) 제공.

설치 방법

npm install -g @dotflash/openapi-semantic-generator

사용 방법

npx openapi-semantic-generator <spec-url-or-path> -o <generated-code-dir> [options]

필수 인자

1. <spec>: OpenAPI 스펙 파일 경로 또는 URL (예: https://.../openapi.json)

옵션

• -o, --output <dir>: 필수. 생성된 코드가 위치한 디렉토리입니다. 이 도구는 해당 디렉토리를 스캔하여 API 파일을 찾습니다.

  • 예시: ./src/api, ./generated/client
  • 중요: 생성된 TypeScript 파일이 반드시 이 디렉토리 또는 하위 디렉토리에 있어야 합니다.

• --api-dir <path>: 선택사항. 출력 디렉토리 기준으로 API 파일이 위치한 상대 경로입니다.

  • 예시: services, api, client/apis
  • 이 경로는 -o 디렉토리 기준의 상대 경로이며, 현재 작업 디렉토리 기준이 아닙니다.
  • 지정하지 않으면 api/, apis/, 출력 디렉토리 자체를 순서대로 검색합니다.

사용 예시

# 기본 사용: API 파일이 ./src/api/에 있는 경우
npx openapi-semantic-generator spec.yaml -o ./src/api

# API 파일이 ./generated/services/에 있는 경우
npx openapi-semantic-generator spec.yaml -o ./generated --api-dir services

# 원격 스펙 URL 사용
npx openapi-semantic-generator https://api.example.com/openapi.json -o ./src/api

# API 파일이 출력 디렉토리 바로 아래에 있는 경우
npx openapi-semantic-generator spec.yaml -o ./dist/client

생성되는 문서

에이전트가 최소한의 토큰으로 API 구조를 파악하고 즉시 구현에 들어갈 수 있도록 두 가지 핵심 문서를 생성합니다.

1. llms.txt (Semantic Index):

   • 전체 API의 용도(Intent), operationId, HTTP 경로, 그리고 실제 TypeScript 소스 파일 위치가 매핑된 통합 인덱스입니다.
   • 에이전트는 이 파일을 통해 어떤 기능을 써야 하는지, 그리고 해당 기능의 타입을 확인하기 위해 어떤 파일을 읽어야 하는지 한눈에 파악합니다.

2. agent.md (에이전트 인터랙션 가이드):

   • agent.md: llms.txt를 어떻게 해석해야 하는지 설명하는 가이드 문서입니다.

💡 AI 에이전트 활용 팁

이 도구의 효과를 극대화하려면, 생성된 파일들을 AI 설정 파일(예: .cursorrules, claude.md, copilot-instructions.md)에 등록하세요.

예시: .cursorrules 또는 claude.md

# API 사용 가이드라인

사용 가능한 API와 사용법을 파악하기 위해 항상 다음 파일을 참조하세요:

- [API 인덱스](openapi/llms.txt)
- [에이전트 가이드](openapi/agent.md)

1. `llms.txt`에서 원하는 작업을 검색하세요.
2. "Source File" 경로에 있는 실제 구현 코드를 읽으세요.
3. 소스 코드에 정의된 대로 올바르게 API를 호출하세요.

• llms.txt를 통한 검색 방법과 소스 코드를 참조하여 구현하는 절차를 정의합니다.

License

MIT