Skip to content

docs: update README.md & rename .env vars #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Psychosynthesis merged 1 commit into from
Oct 31, 2025
Merged

docs: update README.md & rename .env vars #11

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`

## Структура пакета

Copilot AI Oct 30, 2025

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The section heading '## Структура пакета' appears outside of a version entry, which breaks the Keep a Changelog format. This section should either be part of the [3.0.0] release entry (as a subsection with ### heading) or removed if it duplicates information from earlier versions.

Copilot uses AI. Check for mistakes.

```
@gratio/api/
├── LICENSE # Лицензия
├── README.md # Основная документация
├── dist/ # Скомпилированные TypeScript файлы
└── package.json # Конфигурация пакета
```

## [2.0.0] - 2025-09-25

### Добавлено
Expand Down
41 changes: 35 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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`

```
Expand All @@ -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/). Вы можете свободно использовать его в своих целях.
2 changes: 1 addition & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
12 changes: 6 additions & 6 deletions src/commands/gen/endpoints.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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',
},
Expand All @@ -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(
[
Expand Down
12 changes: 6 additions & 6 deletions src/commands/gen/types.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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',
},
Expand All @@ -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);
Expand Down