API Doc 解析器
将 Hydra, Swagger/ OpenAPI, 和 GraphQL 光谱转换为您工具和应用程序的可操作数据 .
api-doc-parser 是一个独立的 TypeScript 库,用于解析 海德拉语Name, (中文(简体) ), 斯瓦格语Name, (中文(简体) ), 打开API,以及 图QL 将文件编入一个统一的中间代表制.
这种正态化的结构使得智能API客户端,代码生成器,管理员接口等等都能够实现.
它与无缝结合 API 平台 框架.
关键特性
- 统一产出 - 一个正常
Api涵盖资源、领域、操作、参数和关系的对象 - 类型脚本第一 - 对每个解析元素严格打字
- 嵌入引用资源( R) 自动解决
- 框架整合 - 容易与API平台生态系统融合
- 支持所有主要 API 格式 — Hydra, Swagger/ OpenAPI v2, OpenAPI v3, 和 GraphQL
* 安装
使用 国家预防机制数字 :
npm install @api-platform/api-doc-parser
使用 N数字 :
pnpm add @api-platform/api-doc-parser
与 雅伦数字 :
yarn add @api-platform/api-doc-parser
使用 阿宝数字 :
bun add @api-platform/api-doc-parser
使用量
海德拉语Name
import { parseHydraDocumentation } from "@api-platform/api-doc-parser";
const { api, response, status } = await parseHydraDocumentation(
"https://demo.api-platform.com",
);
OpenAPI v2( 原名 Swagger)
import { parseSwaggerDocumentation } from "@api-platform/api-doc-parser";
const { api, response, status } = await parseSwaggerDocumentation(
"https://demo.api-platform.com/docs.json",
);
打开API v3
import { parseOpenApi3Documentation } from "@api-platform/api-doc-parser";
const { api, response, status } = await parseOpenApi3Documentation(
"https://demo.api-platform.com/docs.jsonopenapi?spec_version=3.0.0",
);
图QL
import { parseGraphQl } from "@api-platform/api-doc-parser";
const { api, response } = await parseGraphQl(
"https://demo.api-platform.com/graphql",
);
类型定义
每个解析函数返回一个解析对象的保证,其中包含已归正的 API 结构、原始文档和 HTTP 状态代码 :
打开API 3
function parseOpenApi3Documentation(
entrypointUrl: string,
options?: RequestInitExtended,
): Promise<{
api: Api;
response: OpenAPIV3.Document;
status: number;
}>;
斯瓦格语Name
function parseSwaggerDocumentation(entrypointUrl: string): Promise<{
api: Api;
response: OpenAPIV2.Document;
status: number;
}>;
海德拉语Name
function parseHydraDocumentation(
entrypointUrl: string,
options?: RequestInitExtended,
): Promise<{
api: Api;
response: Response;
status: number;
}>;
图QL
function parseGraphQl(
entrypointUrl: string,
options?: RequestInit,
): Promise<{
api: Api;
response: Response;
}>;
阿庇语Name
代表已解析的 API 的根,包含入站点 URL,可选标题,以及资源列表.
interface Api {
entrypoint: string;
title?: string;
resources?: Resource[];
}
资源
描述一个API资源(如实体或收藏),包括其领域、业务和元数据.
interface Resource {
name: string | null;
url: string | null;
id?: string | null;
title?: string | null;
description?: string | null;
deprecated?: boolean | null;
fields?: Field[] | null;
readableFields?: Field[] | null;
writableFields?: Field[] | null;
parameters?: Parameter[] | null;
getParameters?: () => Promise<Parameter[]> | null;
operations?: Operation[] | null;
}
对于水利资源, getParameters() 懒散地装入参数并缓存
寿命计算结果 Resource 举个例子 运行文档
在 API 计划或授权后再次解析以刷新参数
上下文变化.
外地
资源财产,包括其类型、制约因素和元数据.
interface Field {
name: string | null;
id?: string | null;
range?: string | null;
type?: FieldType | null;
arrayType?: FieldType | null;
enum?: { [key: string | number]: string | number } | null;
reference?: string | Resource | null;
embedded?: Resource | null;
required?: boolean | null;
nullable?: boolean | null;
description?: string | null;
maxCardinality?: number | null;
deprecated?: boolean | null;
}
参数
代表一个收集/列表操作的查询参数,例如过滤器或页码变量.
interface Parameter {
variable: string;
range: string | null;
required: boolean;
description: string;
deprecated?: boolean;
}
字段类型
假设一个字段的可能类型,例如字符串、整数、日期等.
type FieldType =
| "string"
| "integer"
| "negativeInteger"
| "nonNegativeInteger"
| "positiveInteger"
| "nonPositiveInteger"
| "number"
| "decimal"
| "double"
| "float"
| "boolean"
| "date"
| "dateTime"
| "duration"
| "time"
| "byte"
| "binary"
| "hexBinary"
| "base64Binary"
| "array"
| "object"
| "email"
| "url"
| "uuid"
| "password"
| string;
运行
代表可以在资源上执行的操作(如GET,POST,PUT,PATCH,DELETE等).
interface Operation {
name: string | null;
type: "show" | "edit" | "delete" | "list" | "create" | null;
method?: string | null;
expects?: any | null;
returns?: string | null;
types?: string[] | null;
deprecated?: boolean | null;
}
QQ OpenAPI 支持
api-doc-parser 在解释 OpenAPI 文档时应用一套可预测的规则.
如果不符合某项规则,则所涉资源将被默默跳出.
| 规则 | 细节 |
|---|---|
| 单个项目路径模式 | A 类 GET (已读)或 PUT编号 :PATCH (更新)终点 必须 匹配 :/books/{id} (单位:千美元) ^[^{}]+/{[^{}]+}/?$) (中文(简体) ).books 可能是单数( o)/book/{id}) (中文(简体) ). |
| Schema 发现 | 获取 ——第一次搜索 responses → 200 → content → application/json; 如果缺少, 倒回 components (组件名称必须是单数,例如:. Book) (中文(简体) ).点/点 仅 requestBody → content → application/json 考虑.如果两者都存在 & PUT/ PATCH 计划,则它们的领域是 合并。 。 。 . |
| 收藏路径 | 创建( A)POST)或清单(GET)终点 必须 复数 :/books。 。 。 . |
| 删除路径 | DELETE 必须在单项 GET 路径下生活(/books/{id}) (中文(简体) ). |
| 关系嵌入( E) | 从财产名称及其JSON计划推断出资源之间的联系: 二. 支助 多元对象/阵列属性 (例如:. reviews, (中文(简体) ), authors成为 内嵌 当项目计划与现有资源相匹配时的资源(Review, (中文(简体) ), Author) (中文(简体) ).二. 支助 类似ID的属性 (例如:. review_id, (中文(简体) ), reviewId, (中文(简体) ), review_ids, (中文(简体) ), reviewIds, (中文(简体) ), authorId)作为 参考文献 对资源.• 因此,如: reviews (对象/阵列)和 review_ids (标记/身份证阵列) 不变 Review 资源,一个标记 内嵌,另一个 参考文献。 。 。 . |
| 参数提取 | 参数改为 仅限 从列表路径( e)/books) (中文(简体) ). |
QQ 支持其它格式( JSON: API, AsyncAPI...)
API Doc Parser旨在解析任何API文档格式并转换为同一种中间代表. 如果您开发了另一种格式的解析器, 请 打开拉请求 把它纳入图书馆.
捐款
欢迎捐款! 协助:
-
读我们 行为守则。 。 。 .
-
叉出寄存器并创建一个特性分支.
-
确保你拥有 最新消息 版本 小时 已安装.
-
安装依赖关系
pnpm install -
遵守代码样式和规则
pnpm lint:fixpnpm format -
运行测试
pnpm test -
确保类型正确
pnpm typecheck -
提交一个拉动请求, 并清楚描述您的更改 .
• 贡献者
QQ 星际历史
• 信贷
创建于 凯文·邓格拉斯发起人: 莱-蒂勒斯.coop。 。 。 .
许可证
这个项目根据麻省理工学院许可证颁发——见 自由主义 详细文件.