# @clementoh/better-openapi-viewer-core 中文文档

规范地址：https://npmcn.com/package/%40clementoh/better-openapi-viewer-core/

版本：0\.1\.8
npm 元数据更新时间：2026-05-12T15:17:47.517Z
中文译文更新时间：2026-11-10T01:07:43.888Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40clementoh/better-openapi-viewer-core
原文对照：https://npmcn.com/package/%40clementoh/better-openapi-viewer-core/?lang=original
项目主页：https://github.com/clementohNZ/better-openapi-viewer#readme
源码仓库：https://github.com/clementohNZ/better-openapi-viewer

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

- 包体积（解压后）：155 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-05-07T04:22:42.488Z
- 最新版本发布：2026-05-12T15:17:47.415Z
- 近 30 天下载量：5636（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

框架-不可知 OpenAPI 正常化与取景器原始.

## 安装

```sh
npm install @clementoh/better-openapi-viewer-core
```

也可以使用：`pnpm add @clementoh/better-openapi-viewer-core`、`yarn add @clementoh/better-openapi-viewer-core`、`bun add @clementoh/better-openapi-viewer-core`

## README

# @clementoh/更好-openapi-viewer-core 页面存档备份,存于互联网档案馆

框架-不可知 OpenAPI 正常化与取景器原始.

## 当前原始人

-   用于检测OpenAPI 3.0,OpenAPI 3.1,和Swagger 2.0文档的文档摄取帮助.
-   JSON内部指针 `$ref` 常规化文档的解析,加外部 `$ref` 解决器脚手架,可以称为消费者提供的装载器.
-   用标签、参数、响应、计划、认证、内容类型、服务器和供应商延伸元数据提取操作.
-   搜索,过滤,和标签分组 帮助导航和发现.
-   Schema树, schema 类型,以及用于后期UI渲染的 schema/media/Response 示例助手.
-   具有状态范围/类别分类和Swagger 2.0反应正常化帮助者 `produces` 堕倒.
-   请求 OpenAPI 3.x 的正体介质类型发现 `requestBody.content` 和 Swagger 2.0 体/形式参数.
-   参数和请求体验证工具,用于所需值、计划类型、enum、常数、对象属性、阵列和组成保护.
-   OpenAPI 3.x 的安全方案提取 `components.securitySchemes` 和 Swagger 2.0 组合键 `securityDefinitions`,包括 OAuth 流元数据和 OpenID 连接发现 URL.
-   需要通过Markdown-aware表面得到的描述.
-   尝试 It Out 请求原始的服务器选择和变量替换,服务器变量默认/选项,常见参数序列化样式(`form`, (中文(简体) ), `simple`, (中文(简体) ), `spaceDelimited`, (中文(简体) ), `pipeDelimited`, (中文(简体) ), `deepObject`, (中文(简体) ), `matrix`,以及 `label`),请求URL/header/cookie/body构造,基本/承接者/api-key/OAuth/OpenID证书应用程序,授权前证书合并,请求/应答截取器钩,以及卷曲/截取/httpie/python片断生成.
-   查看器配置原始的路由路径,JSON路径,标题,布局,默认扩展,深链接,过滤,请求持续时间显示,坚持auth,语法突出,支持提交方法,操作/tag排序器,模型扩展深度,以及插件元数据.

## 查看器配置

`ViewerConfig` 抓取框架-不可知的接子适配器,UI可以不依赖特定的渲染器而共享. 使用 `mergeViewerConfig` 到层包默认值,适配器默认值,以及用户覆盖值.

```ts
import { mergeViewerConfig } from '@clementoh/better-openapi-viewer-core';

const config = mergeViewerConfig({
  title: 'Example API',
  defaultExpansion: 'list',
  deepLinking: true,
  filter: true,
  displayRequestDuration: true,
  persistAuthorization: false,
  supportedSubmitMethods: ['get', 'post', 'patch', 'delete'],
  operationsSorter: 'alpha',
  tagsSorter: 'alpha',
  defaultModelExpandDepth: 2,
});
```

`sortOperations`, (中文(简体) ), `sortOperationTags`,以及 `isSubmitMethodSupported` 为想要在不同运行时间尊重相同配置的消费者提供可重复使用的行为.

## 试试看吧

`buildTryItOutRequest` 建立框架中立的请求模式。 消费者可以在执行前提供请求截取器,并在自己的HTTP客户端返回后应用响应截取器.

```ts
import { applyTryItOutResponseInterceptor, buildTryItOutRequest, generateRequestSnippet } from '@clementoh/better-openapi-viewer-core';

const request = buildTryItOutRequest({
  operation,
  parameters: { id: 42 },
  interceptors: {
    request: (next) => ({ ...next, headers: { ...next.headers, 'X-Client': 'docs' } }),
    response: (next) => next,
  },
});

const snippet = generateRequestSnippet(request, 'fetch');
const response = applyTryItOutResponseInterceptor({ status: 200, headers: {}, body: {} }, { operation }, request);
```

使用 `resolveReference(document, ref, { loader })` 当一个渲染器或适配器想要解决外部引用时。 内部 `#/...` 首先从提供的文档中解析指针;只有在装入器提供时才获取非内部的取出指针.

## 验证和认证元数据

Core 暴露出渲染器软件包在发送 Try It Out 请求前可以调用的已输入的帮助器.

```ts
import {
  getOpenIdConnectUrls,
  getSecuritySchemes,
  getSecuritySchemeMetadata,
  mergePreauthorizedCredentials,
  validateParameterValues,
  validateRequestBody,
} from '@clementoh/better-openapi-viewer-core';

const parameterResult = validateParameterValues({
  parameters: operation.parameters,
  values: { id: 42 },
});

const bodyResult = validateRequestBody({
  requestBody: operation.requestBody,
  body: { name: 'Ada' },
  contentType: 'application/json',
});

const securityMetadata = getSecuritySchemeMetadata(getSecuritySchemes(document));
const openIdUrls = getOpenIdConnectUrls(getSecuritySchemes(document));
const oauthFlows = securityMetadata.flatMap((scheme) => scheme.oauthFlows);

const auth = mergePreauthorizedCredentials({
  auth: {
    bearerAuth: { value: 'token' },
    oauth: { value: 'access-token', scopes: ['read:users'] },
  },
});
```

## 服务器变量

服务器可变帮助者会曝光默认,并允许选项而不将消费者绑定在一个UI.

```ts
import { getServerVariableDefaults, getServerVariableOptions, normalizeServerVariables, selectServerUrl } from '@clementoh/better-openapi-viewer-core';

const variables = normalizeServerVariables(server, { environment: 'staging' });
const url = selectServerUrl([server], { variables });
const defaults = getServerVariableDefaults(server);
const options = getServerVariableOptions(server);
```

## 常见问题

### @clementoh/better-openapi-viewer-core 是什么？

框架-不可知 OpenAPI 正常化与取景器原始\.

### 如何安装 @clementoh/better-openapi-viewer-core？

在项目目录运行 npm install @clementoh/better-openapi-viewer-core，或使用 pnpm add / yarn add / bun add。

### @clementoh/better-openapi-viewer-core 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @clementoh/better-openapi-viewer-core 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @clementoh/better-openapi-viewer-core 可以商用吗？

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

### @clementoh/better-openapi-viewer-core 的下载量有多少？

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

### @clementoh/better-openapi-viewer-core 还在维护吗？

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