# @apielements/core 中文文档

规范地址：https://npmcn.com/package/%40apielements/core/

版本：0\.2\.1
npm 元数据更新时间：2022-06-28T21:36:06.655Z
中文译文更新时间：2026-11-06T10:00:33.880Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40apielements/core
原文对照：https://npmcn.com/package/%40apielements/core/?lang=original
项目主页：https://github.com/apiaryio/api-elements.js/tree/master/packages/core
源码仓库：https://github.com/apiaryio/api-elements.js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：23.3 kB，5 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=8
- 运行依赖：1 个
- 首次发布：2020-06-12T14:46:15.608Z
- 最新版本发布：2020-09-02T11:46:20.263Z
- 近 30 天下载量：27821（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 0 个）

## 中文简介

API 描述 SDK

## 安装

```sh
npm install @apielements/core
```

也可以使用：`pnpm add @apielements/core`、`yarn add @apielements/core`、`bun add @apielements/core`

## README

# API 要素:核心

[![NPM version](https://img.shields.io/npm/v/@apielements/core.svg)](https://www.npmjs.org/package/@apielements/core) [![License](https://img.shields.io/npm/l/@apielements/core.svg)](https://www.npmjs.org/package/@apielements/core)

API 描述 SDK

> _华德迪: [我有过的最好的工作](http://www.imdb.com/title/tt2713180/quotes?item=qt2267083)。 。 。 ._

Fury为API描述格式提供统一接口,例如: [API 蓝图](https://apiblueprint.org/) 财务报告和审定财务报表 [斯瓦格语Name](http://swagger.io/)。 。 。 .

说明:要求 _适配器_ 支持解析和序列化。 您需要安装至少一个适配器 。 你们可以 [找到怒火适配器](https://www.npmjs.com/search?q=fury-adapter) 通过npm.

## 使用量

### 安装

Fury.js作为npm模块提供.

```sh
$ npm install --save @apielements/core
```

### 折射接口

Fury.js 提供了基于 [折射项目](https://github.com/refractproject/refract-spec) 元素规格,并使用 API 描述和数据结构命名空间。 适配器从API Bluprint等格式转换为Refract元素和Fury.js曝光了这些与API相关的便利功能. 例如:

```js
import fury from '@apielements/core';
import apibParser from '@apielements/apib-parser';

// The input as a string
const source = 'FORMAT: 1A\n# My API\n...';

// Use the API Blueprint parser adapter
fury.use(apibParser);

// Parse the input and print 'My API'
const parseResult = await fury.parse({ source });
console.log(parseResult.api.title);
```

一旦你得到一个解析的API,它很容易通过:

```js
parseResult.api.resourceGroups.forEach(function (resourceGroup) {
  console.log(resourceGroup.title);

  resourceGroup.resources.forEach(function (resource) {
    console.log(resource.title);

    resource.transitions.forEach(function (transition) {
      console.log(transition.title);

      transition.transactions.forEach(function (transaction) {
        const request = transaction.request;
        const response = transaction.response;

        console.log(`${request.method} ${request.href}`);
        console.log(`${response.statusCode} (${response.header('Content-Type')})`);
        console.log(response.messageBody);
      });
    });
  });
});
```

还可以进行复杂的全文件搜索和过滤。 例如,要打印所有定义的示例请求的 HTTP 方法和路径列表 :

```js
/*
 * Prints out something like:
 *
 * POST /frobs
 * GET /frobs
 * GET /frobs/{id}
 * PUT /frobs/{id}
 * DELETE /frobs/{id}
 */
function filterFunc(item) {
  if (item.element === 'httpRequest' && item.statusCode === 200) {
    return true;
  }

  return false;
}

console.log('All API request URIs:');

api.find(filterFunc).forEach(function (request) {
  console.log(`${request.method} ${request.href}`)
});
```

参考:

-   [最小](https://github.com/refractproject/minim)

#### 多个怒火事件

可能有一天,您需要用不同的适配器或者在同一程序中设置的其他选项来进行多个Fury事件. 这可以通过 `Fury` 类 :

```js
import {Fury} from '@apielements/core';

const fury1 = new Fury();
const fury2 = new Fury();

await fury1.parse(...);
```

#### 写入适配器

适配器从API Bluprint等输入格式转换为Refract元素. 这使得一个单一的,一致的界面可以用于与多个输入的API描述格式交互. 写入自己的适配器允许您添加对新输入格式的支持.

说明 `mediaTypes`:它允许两种定义. 第一个是 **数组** 类型。 它旨在“抓住一切”实施. 如果适配器只执行一种愤怒的方法,或者如果所有的方法都接受同一种类型的媒体类型,那么这是有用的.

另一个可能的选择是使用带有方法映射名称的对象来进行MediaTyps的阵列. 它可以更好地进行颗粒性检测.

实例:

如果适配器只支持一种方法或所有方法支持同一种输入媒体类型:

```js
export const mediaTypes = ['text/vnd.my-adapter'];
```

如果您需要区分支持的输入 媒体类型 :

```js
export const mediaTypes = {
  parse: ['text/vnd.my-parsing', 'text/vnd.another-supported-parsing'],
  serialize: ['text/vnd.my-serialization'],
};
```

适配器由名称,媒体类型列表组成,最多可选四种公共功能: `detect`, (中文(简体) ), `parse`, (中文(简体) ), `serialize` 财务报告和审定财务报表 `serializeSync`。一个简单的例子可能是这样的:

```js
export const name = 'my-adapter';
export const mediaTypes = ['text/vnd.my-adapter'];

export function detect(source[, method]) {
  // If no media type is know, then we fall back to auto-detection. Here you
  // can check the source and see if you think you can parse it.
  // 
  // optional parmeter `method` give you hint about caller is going to invoke
  // note that value can be undefined
  return source.match(/some-test/i) !== null;
}

export async function parse({minim, generateSourceMap, mediaType, source}) {
  // Here you convert the source into refract elements. Use the `minim`
  // variable to access refract element classes.
  const Resource = minim.getElementByClass('resource');
  // ...
  return elements;
}

export async function validate({minim, mediaType, source}) {
  // Here you validate the source and return a parse result for any warnings or
  // errors.
  //
  // NOTE: Implementing `validate` is optional, Fury will fallback to using
  // `parse` to find warnings or errors.
  return null;
}

export async function serialize({api, mediaType, minim}) {
  // Here you convert `api` from javascript element objects to the serialized
  // source format.
  // ...
  return outputString;
}

export function serializeSync({api, mediaType, minim}) {
  // Here you convert `api` from javascript element objects to the serialized
  // source format.
  // ...
  return outputString;
}

export default {name, mediaTypes, detect, parse, serialize, serializeSync};
```

现在您可以用 Fury.js 注册适配器 :

```js
import fury from '@apielements/core';
import myAdapter from './my-adapter';

// Register my custom adapter
fury.use(myAdapter);

// Now parse my custom input format!
const parseResult = await fury.parse({ source: 'some-test\n...' });
console.log(parseResult.api.title);
```

## 常见问题

### @apielements/core 是什么？

API 描述 SDK

### 如何安装 @apielements/core？

在项目目录运行 npm install @apielements/core，或使用 pnpm add / yarn add / bun add。

### @apielements/core 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/apielements\_\_core 是否存在。

### @apielements/core 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @apielements/core 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=8。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @apielements/core 可以商用吗？

@apielements/core 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @apielements/core 的下载量有多少？

根据 npm 官方下载统计，@apielements/core 在 2026/10/06 – 2026/11/04 这 30 天内被下载 27,821 次，日均约 927 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @apielements/core 还在维护吗？

最新版本 0\.2\.1 发布于 2020/09/02（6 年前）；至今共发布 3 个版本，其中过去 12 个月发布了 0 个；首次发布于 2020/06/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。