diff --git a/CHANGELOG.md b/CHANGELOG.md index 03d3899..c49f87c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,29 @@ Формат основан на [Keep a Changelog](https://keepachangelog.com/ru/1.0.0/), и этот проект придерживается [Semantic Versioning](https://semver.org/lang/ru/). +## [3.0.0] - 2025-10-30 + +### Изменено + +- Обновлена документация для улучшения понимания возможностей пакета +- Названия переменных окружения теперь лучше отражают их назначение + - `GRATIO_TYPES_LINK` → `OPENAPI_TYPES_LINK` + - `GRATIO_TYPES_TOKEN` → `OPENAPI_TYPES_TOKEN` + - `GRATIO_TYPES_OUTPUT` → `OPENAPI_TYPES_OUTPUT` + - `GRATIO_ENDPOINTS_LINK` → `OPENAPI_ENDPOINTS_LINK` + - `GRATIO_ENDPOINTS_TOKEN` → `OPENAPI_ENDPOINTS_TOKEN` + - `GRATIO_ENDPOINTS_OUTPUT` → `OPENAPI_ENDPOINTS_OUTPUT` + +## Структура пакета + +``` +@gratio/api/ +├── LICENSE # Лицензия +├── README.md # Основная документация +├── dist/ # Скомпилированные TypeScript файлы +└── package.json # Конфигурация пакета +``` + ## [2.0.0] - 2025-09-25 ### Добавлено diff --git a/README.md b/README.md index 20ac819..60ff341 100644 --- a/README.md +++ b/README.md @@ -59,6 +59,31 @@ api gen endpoints --link https://api.example.com/openapi.json npx @gratio/api gen endpoints --link ./api/schema.json ``` +## Конфигурация через .env + +Если флаг `--link` не указан, CLI берёт значение из переменных окружения, которые автоматически подгружаются из файла `.env` в корне проекта (используется dotenv). Для команд действуют такие переменные: + +- Для `gen types`: `OPENAPI_TYPES_LINK`, `OPENAPI_TYPES_TOKEN`, `OPENAPI_TYPES_OUTPUT` +- Для `gen endpoints`: `OPENAPI_ENDPOINTS_LINK`, `OPENAPI_ENDPOINTS_TOKEN`, `OPENAPI_ENDPOINTS_OUTPUT` + +Пример файла `.env`: + +``` +# OpenAPI источник (URL или локальный файл) +OPENAPI_TYPES_LINK=https://api.example.com/openapi.json +OPENAPI_ENDPOINTS_LINK=./api/schema.json + +# Токены доступа (нужны для приватных репозиториев GitHub/GitLab) +OPENAPI_TYPES_TOKEN=ghp_your_token_here +OPENAPI_ENDPOINTS_TOKEN=glpat_your_token_here + +# Куда писать результат (по умолчанию выводится в stdout) +OPENAPI_TYPES_OUTPUT=src/types/api.ts +OPENAPI_ENDPOINTS_OUTPUT=src/types/endpoints.ts +``` + +Примечание: если переменные не заданы и включены подсказки (`--prompt` по умолчанию), CLI спросит недостающие значения интерактивно. В CI/production режиме подсказки отключаются. + ## Доступные типы ### Основные типы API @@ -114,11 +139,13 @@ Generates types using OpenAPI 3 specification. Flags: -s, --silent Suppresses all console output except errors. -p, --prompt Whether to prompt for missing information like spec URL or PAT. - -l, --link The URL to the OpenAPI specification (GRATIO_TYPES_LINK). - -P, --token Personal Access Token with api scope (GRATIO_TYPES_TOKEN). - -o, --output The output path for the generated types file (GRATIO_TYPES_OUTPUT). + -l, --link The URL to the OpenAPI specification (OPENAPI_TYPES_LINK). + -P, --token Personal Access Token with api scope (OPENAPI_TYPES_TOKEN). + -o, --output The output path for the generated types file (OPENAPI_TYPES_OUTPUT). ``` +Примечание: значение для `--link` может быть как URL, так и путём к локальному файлу (например, `./api/schema.json`). + ## `@gratio/api gen endpoints --help` ``` @@ -130,11 +157,13 @@ Generates endpoint enum with data from OpenAPI 3 specification. Flags: -s, --silent Suppresses all console output except errors. -p, --prompt Whether to prompt for missing information like spec URL or PAT. - -l, --link The URL to the OpenAPI specification (GRATIO_ENDPOINTS_LINK). - -P, --token Personal Access Token with api scope (GRATIO_ENDPOINTS_TOKEN). - -o, --output The output path for the generated endpoint file (GRATIO_ENDPOINTS_OUTPUT). + -l, --link The URL to the OpenAPI specification (OPENAPI_ENDPOINTS_LINK). + -P, --token Personal Access Token with api scope (OPENAPI_ENDPOINTS_TOKEN). + -o, --output The output path for the generated endpoint file (OPENAPI_ENDPOINTS_OUTPUT). ``` +Примечание: значение для `--link` может быть как URL, так и путём к локальному файлу (например, `./api/schema.json`). + ## Лицензия Этот проект находится под лицензией [MIT](https://choosealicense.com/licenses/mit/). Вы можете свободно использовать его в своих целях. diff --git a/package.json b/package.json index 0810bd8..a864bb5 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@gratio/api", - "version": "2.0.0", + "version": "3.0.0", "description": "TypeScript common types for Gratio projects API responses and requests", "homepage": "https://github.com/Gratio-tech/Api#readme", "packageManager": "bun@1.2.17", diff --git a/src/commands/gen/endpoints.ts b/src/commands/gen/endpoints.ts index 7e72b89..718732a 100644 --- a/src/commands/gen/endpoints.ts +++ b/src/commands/gen/endpoints.ts @@ -83,17 +83,17 @@ export default defineCommand({ }, link: { type: 'string', - description: 'The URL to the OpenAPI specification (GRATIO_ENDPOINTS_LINK).', + description: 'The URL to the OpenAPI specification (OPENAPI_ENDPOINTS_LINK).', short: 'l', }, token: { type: 'string', - description: 'Personal Access Token with api scope (GRATIO_ENDPOINTS_TOKEN).', + description: 'Personal Access Token with api scope (OPENAPI_ENDPOINTS_TOKEN).', short: 'P', }, output: { type: 'string', - description: 'The output path for the generated endpoint file (GRATIO_ENDPOINTS_OUTPUT).', + description: 'The output path for the generated endpoint file (OPENAPI_ENDPOINTS_OUTPUT).', short: 'o', default: 'stdout', }, @@ -106,13 +106,13 @@ export default defineCommand({ } try { - const specLink = await getSpecLink(args, 'GRATIO_ENDPOINTS_LINK'); + const specLink = await getSpecLink(args, 'OPENAPI_ENDPOINTS_LINK'); - const specContents = await getSpecContents(specLink, args, 'GRATIO_ENDPOINTS_TOKEN'); + const specContents = await getSpecContents(specLink, args, 'OPENAPI_ENDPOINTS_TOKEN'); const spec = parseSpec(specContents); const paths = getPaths(spec); - const outputPath = args.output ?? process.env.GRATIO_ENDPOINTS_OUTPUT; + const outputPath = args.output ?? process.env.OPENAPI_ENDPOINTS_OUTPUT; const template = createTemplate( [ diff --git a/src/commands/gen/types.ts b/src/commands/gen/types.ts index 136fe16..fa3ea68 100644 --- a/src/commands/gen/types.ts +++ b/src/commands/gen/types.ts @@ -25,17 +25,17 @@ export default defineCommand({ }, link: { type: 'string', - description: 'The URL to the OpenAPI specification (GRATIO_TYPES_LINK).', + description: 'The URL to the OpenAPI specification (OPENAPI_TYPES_LINK).', short: 'l', }, token: { type: 'string', - description: 'Personal Access Token with api scope (GRATIO_TYPES_TOKEN).', + description: 'Personal Access Token with api scope (OPENAPI_TYPES_TOKEN).', short: 'P', }, output: { type: 'string', - description: 'The output path for the generated types file (GRATIO_TYPES_OUTPUT).', + description: 'The output path for the generated types file (OPENAPI_TYPES_OUTPUT).', short: 'o', default: 'stdout', }, @@ -52,15 +52,15 @@ export default defineCommand({ const openApiImport = import('openapi-typescript'); try { - const specLink = await getSpecLink(args, 'GRATIO_TYPES_LINK'); + const specLink = await getSpecLink(args, 'OPENAPI_TYPES_LINK'); - const specContents = await getSpecContents(specLink, args, 'GRATIO_TYPES_TOKEN'); + const specContents = await getSpecContents(specLink, args, 'OPENAPI_TYPES_TOKEN'); const { astToString, default: openapiTS } = await openApiImport; const ast = await openapiTS(specContents); const contents = astToString(ast); - const outputPath = args.output ?? process.env.GRATIO_TYPES_OUTPUT; + const outputPath = args.output ?? process.env.OPENAPI_TYPES_OUTPUT; if (outputPath === 'stdout') { console.log(contents);