OpenAPI3-TS 项目使用教程

1. 项目目录结构及介绍

OpenAPI3-TS 项目的目录结构如下：

openapi3-ts/
├── docs/
├── src/
│   ├── model/
│   ├── dsl/
│   └── index.ts
├── test/
├── .eslintignore
├── .eslintrc.js
├── .gitignore
├── .npmignore
├── .prettierignore
├── .prettierrc.js
├── CHANGELOG.md
├── LICENSE
├── README.md
├── package.json
├── tsconfig.json
└── vite.config.d.mts

目录结构介绍

• docs/: 存放项目的文档文件。
• src/: 项目的源代码目录。
  • model/: 存放 OpenAPI 3.x 的 TypeScript 类型定义文件。
  • dsl/: 存放用于构建 OpenAPI 3.x 合同的 DSL（领域特定语言）代码。
  • index.ts: 项目的入口文件。
• test/: 存放项目的测试代码。
• .eslintignore: ESLint 忽略文件列表。
• .eslintrc.js: ESLint 配置文件。
• .gitignore: Git 忽略文件列表。
• .npmignore: npm 发布时忽略的文件列表。
• .prettierignore: Prettier 忽略文件列表。
• .prettierrc.js: Prettier 配置文件。
• CHANGELOG.md: 项目变更日志。
• LICENSE: 项目许可证文件。
• README.md: 项目介绍和使用说明。
• package.json: 项目的 npm 配置文件，包含依赖、脚本等信息。
• tsconfig.json: TypeScript 配置文件。
• vite.config.d.mts: Vite 配置文件。

2. 项目启动文件介绍

项目的入口文件是 src/index.ts。该文件主要负责导出项目的主要功能模块，包括 OpenAPI 3.0 和 3.1 的模型和 DSL。

主要代码片段

// src/index.ts

export * as oas30 from './model/v3.0';
export * as oas31 from './model/v3.1';

使用示例

import { oas30, oas31 } from 'openapi3-ts';

const apiSpec: oas30.OpenAPIObject = {
  openapi: '3.0.0',
  info: {
    title: 'Example API',
    version: '1.0.0',
  },
  paths: {},
};

3. 项目配置文件介绍

package.json

package.json 文件包含了项目的依赖、脚本、版本等信息。以下是一些关键配置项：

{
  "name": "openapi3-ts",
  "version": "4.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "tsc",
    "test": "jest",
    "lint": "eslint src test --ext .ts"
  },
  "dependencies": {
    "typescript": "^4.0.0"
  },
  "devDependencies": {
    "@types/jest": "^26.0.0",
    "eslint": "^7.0.0",
    "jest": "^26.0.0",
    "prettier": "^2.0.0"
  }
}

tsconfig.json

tsconfig.json 文件用于配置 TypeScript 编译选项。以下是一些关键配置项：

{
  "compilerOptions": {
    "target": "ES2018",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

.eslintrc.js

.eslintrc.js 文件用于配置 ESLint，确保代码风格一致。以下是一些关键配置项：

module.exports = {
  root: true,
  parser: '@typescript-eslint/parser',
  plugins: ['@typescript-eslint'],
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
  ],
  rules: {
    // 自定义规则
  }
};

.prettierrc.js

.prettierrc.js 文件用于配置 Prettier，确保代码格式化风格一致。以下是一些关键配置项：

module.exports = {
  singleQuote: true,
  trailingComma: 'all',
  printWidth: 80,
};

通过以上配置文件，可以确保项目的代码质量和一致性。