@abitechdev/openchasqui 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +245 -12
- package/package.json +23 -11
package/README.md
CHANGED
|
@@ -1,21 +1,254 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<picture>
|
|
3
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/abitech-dev/abitech-openchasqui-cli/main/.github/assets/logo-dark.svg">
|
|
4
|
+
<img alt="OpenChasqui" src="https://raw.githubusercontent.com/abitech-dev/abitech-openchasqui-cli/main/.github/assets/logo-light.svg" width="400">
|
|
5
|
+
</picture>
|
|
6
|
+
</p>
|
|
2
7
|
|
|
3
|
-
|
|
8
|
+
<p align="center">
|
|
9
|
+
<strong>Tu contrato OpenAPI, entregado como colecciones de Postman y Bruno con pruebas.</strong>
|
|
10
|
+
</p>
|
|
4
11
|
|
|
5
|
-
|
|
12
|
+
<p align="center">
|
|
13
|
+
<a href="https://www.npmjs.com/package/@abitechdev/openchasqui"><img alt="npm" src="https://img.shields.io/npm/v/@abitechdev/openchasqui?color=c2410c&label=npm"></a>
|
|
14
|
+
<a href="https://github.com/abitech-dev/abitech-openchasqui-cli/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/abitech-dev/abitech-openchasqui-cli/actions/workflows/ci.yml/badge.svg"></a>
|
|
15
|
+
<img alt="Node.js 22 o superior" src="https://img.shields.io/badge/node-%E2%89%A522-339933">
|
|
16
|
+
<img alt="OpenAPI 3.0 y 3.1" src="https://img.shields.io/badge/OpenAPI-3.0%20%7C%203.1-6ba539">
|
|
17
|
+
<a href="https://github.com/abitech-dev/abitech-openchasqui-cli/blob/main/LICENSE"><img alt="Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue"></a>
|
|
18
|
+
</p>
|
|
6
19
|
|
|
7
|
-
|
|
20
|
+
<p align="center">
|
|
21
|
+
<a href="#instalación">Instalación</a> ·
|
|
22
|
+
<a href="#inicio-rápido">Inicio rápido</a> ·
|
|
23
|
+
<a href="#configuración">Configuración</a> ·
|
|
24
|
+
<a href="#overlays">Overlays</a> ·
|
|
25
|
+
<a href="#políticas">Políticas</a> ·
|
|
26
|
+
<a href="#paquetes">Paquetes</a> ·
|
|
27
|
+
<a href="https://github.com/abitech-dev/abitech-openchasqui-cli/blob/main/README.en.md">English</a>
|
|
28
|
+
</p>
|
|
29
|
+
|
|
30
|
+
<p align="center">
|
|
31
|
+
<img alt="openchasqui generate seguido de una corrida de Bruno con 20 de 20 pruebas aprobadas" src="https://raw.githubusercontent.com/abitech-dev/abitech-openchasqui-cli/main/.github/assets/terminal.svg" width="760">
|
|
32
|
+
</p>
|
|
33
|
+
|
|
34
|
+
El _chasqui_ llevaba mensajes por la red de caminos inca. OpenChasqui lleva tu
|
|
35
|
+
contrato de API a cada herramienta que usa tu equipo: un comando convierte un
|
|
36
|
+
documento OpenAPI en colecciones con entornos, ejemplos realistas y pruebas de
|
|
37
|
+
contrato, y el CI evita que se desactualicen.
|
|
38
|
+
|
|
39
|
+
> [!NOTE]
|
|
40
|
+
> OpenChasqui está en desarrollo temprano (0.x). La configuración y el contrato
|
|
41
|
+
> de plugins pueden cambiar antes de la 1.0.
|
|
42
|
+
|
|
43
|
+
## Características
|
|
44
|
+
|
|
45
|
+
| | |
|
|
46
|
+
| -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
|
47
|
+
| **Una sola fuente de verdad.** Las colecciones se generan desde el contrato y nunca se editan a mano, así que no se separan de la API. | **Pruebas incluidas.** Cada petición comprueba su estado, tipo de contenido, esquema de respuesta y tiempo de respuesta. |
|
|
48
|
+
| **Postman y Bruno.** Postman Collection v2.1 y Bruno OpenCollection YAML en la misma corrida. | **Overlays.** Renombra, reagrupa u oculta endpoints con OpenAPI Overlay 1.0, sin tocar el contrato. |
|
|
49
|
+
| **Datos realistas.** Ejemplos deterministas, con DNI, RUC, celulares y ubigeo peruanos cuando los pidas. | **Seguro por defecto.** Los secretos nunca llevan valor, los ejemplos no pueden traer tokens y solo se sobrescriben sus propias carpetas. |
|
|
50
|
+
|
|
51
|
+
## Herramientas
|
|
52
|
+
|
|
53
|
+
Elige una o varias en `targets`; `targets: [bruno]` genera solo Bruno.
|
|
54
|
+
|
|
55
|
+
| Herramienta | `targets` | Estado |
|
|
56
|
+
| ------------------------------------- | --------- | ------------- |
|
|
57
|
+
| Postman (Collection v2.1) | `postman` | Disponible |
|
|
58
|
+
| Bruno (OpenCollection YAML) | `bruno` | Disponible |
|
|
59
|
+
| Archivos `.http` (VS Code, JetBrains) | | Planeado, 1.2 |
|
|
60
|
+
| Insomnia | | Planeado, 1.2 |
|
|
61
|
+
| k6 y Playwright | | Planeado, 2.0 |
|
|
62
|
+
|
|
63
|
+
Cada herramienta es un plugin emisor; sumar una no toca el núcleo.
|
|
64
|
+
|
|
65
|
+
## Instalación
|
|
66
|
+
|
|
67
|
+
Requiere Node.js 22 o superior. Instálalo como dependencia de desarrollo del
|
|
68
|
+
proyecto que tiene el contrato:
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
npm i -D @abitechdev/openchasqui
|
|
72
|
+
pnpm add -D @abitechdev/openchasqui
|
|
73
|
+
yarn add -D @abitechdev/openchasqui
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Así el comando queda como `npx openchasqui`. También funciona sin instalar,
|
|
77
|
+
con `npx @abitechdev/openchasqui`.
|
|
78
|
+
|
|
79
|
+
## Inicio rápido
|
|
80
|
+
|
|
81
|
+
En la carpeta de tu `openapi.yaml`:
|
|
8
82
|
|
|
9
83
|
```bash
|
|
10
|
-
npx @abitechdev/openchasqui init #
|
|
11
|
-
npx @abitechdev/openchasqui generate #
|
|
12
|
-
npx @abitechdev/openchasqui verify #
|
|
84
|
+
npx @abitechdev/openchasqui init # crea openchasqui.config.yaml
|
|
85
|
+
npx @abitechdev/openchasqui generate # escribe collections/postman y collections/bruno
|
|
86
|
+
npx @abitechdev/openchasqui verify # en CI: políticas en verde y colecciones al día
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Importa la carpeta en Postman o Bruno, o córrela desde la línea de comandos:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
npx newman run collections/postman/*.postman_collection.json \
|
|
93
|
+
-e collections/postman/*-dev.postman_environment.json
|
|
94
|
+
cd collections/bruno && npx @usebruno/cli run --env dev
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## Cómo funciona
|
|
98
|
+
|
|
99
|
+
```mermaid
|
|
100
|
+
flowchart LR
|
|
101
|
+
A[OpenAPI 3.0 / 3.1] --> B[Overlays]
|
|
102
|
+
B --> C[Cargador]
|
|
103
|
+
C --> D[Ejemplos y pruebas]
|
|
104
|
+
D --> E[Políticas]
|
|
105
|
+
E --> F[Postman v2.1]
|
|
106
|
+
E --> G[Bruno OpenCollection]
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Cada paso es un plugin. El mismo contrato produce siempre los mismos archivos,
|
|
110
|
+
así que `verify` detecta en CI cualquier colección desactualizada.
|
|
111
|
+
|
|
112
|
+
## Qué obtienes
|
|
113
|
+
|
|
114
|
+
```text
|
|
115
|
+
collections/
|
|
116
|
+
├── postman/
|
|
117
|
+
│ ├── petstore.postman_collection.json
|
|
118
|
+
│ └── petstore-dev.postman_environment.json
|
|
119
|
+
└── bruno/
|
|
120
|
+
├── opencollection.yml
|
|
121
|
+
├── environments/dev.yml
|
|
122
|
+
├── pets/
|
|
123
|
+
│ ├── folder.yml
|
|
124
|
+
│ ├── List pets.yml
|
|
125
|
+
│ └── Create a pet.yml
|
|
126
|
+
└── store/
|
|
127
|
+
└── Opening hours.yml
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Cada petición trae sus pruebas: código de estado, tipo de contenido, esquema de
|
|
131
|
+
la respuesta y tiempo de respuesta.
|
|
132
|
+
|
|
133
|
+
Con `data: es-pe`, los ejemplos que faltan se llenan con datos de prueba
|
|
134
|
+
peruanos con la forma de una consulta a RENIEC: uno o dos nombres, los dos
|
|
135
|
+
apellidos, una persona y un lugar por objeto, y un RUC con dígito verificador
|
|
136
|
+
SUNAT válido:
|
|
137
|
+
|
|
138
|
+
```json
|
|
139
|
+
{
|
|
140
|
+
"nombres": "Isabel Lucía",
|
|
141
|
+
"apellidoPaterno": "Gutiérrez",
|
|
142
|
+
"apellidoMaterno": "Castillo",
|
|
143
|
+
"correo": "isabel.gutierrez@example.com",
|
|
144
|
+
"dni": "11067581",
|
|
145
|
+
"ruc": "20968504291",
|
|
146
|
+
"celular": "925340375",
|
|
147
|
+
"ubigeo": "170101",
|
|
148
|
+
"distrito": "Tambopata"
|
|
149
|
+
}
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
## Configuración
|
|
153
|
+
|
|
154
|
+
```yaml
|
|
155
|
+
version: 1
|
|
156
|
+
source: openapi.yaml
|
|
157
|
+
overlays: [names.overlay.yaml]
|
|
158
|
+
data: es-pe
|
|
159
|
+
targets: [postman, bruno]
|
|
160
|
+
output: collections
|
|
161
|
+
environments:
|
|
162
|
+
qa:
|
|
163
|
+
variables:
|
|
164
|
+
baseUrl: https://api.qa.example.com
|
|
165
|
+
secrets: [token]
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
| Clave | Obligatoria | Descripción |
|
|
169
|
+
| -------------- | ----------- | --------------------------------------------------------------------- |
|
|
170
|
+
| `version` | sí | Versión de la configuración, `1` |
|
|
171
|
+
| `source` | sí | Documento OpenAPI 3.0 o 3.1, en JSON o YAML |
|
|
172
|
+
| `targets` | sí | `postman`, `bruno` o ambos |
|
|
173
|
+
| `output` | sí | Carpeta de las colecciones, una subcarpeta por destino |
|
|
174
|
+
| `overlays` | no | Documentos [Overlay 1.0](https://spec.openapis.org/overlay/v1.0.html) |
|
|
175
|
+
| `data` | no | Ejemplos sintéticos: `generic` (por defecto) o `es-pe` |
|
|
176
|
+
| `environments` | no | Variables y nombres de secretos por entorno |
|
|
177
|
+
| `variables` | no | Nombres de las variables de URL base, token y API key |
|
|
178
|
+
| `tests` | no | `responseTimeMs`, la respuesta más lenta aceptable (por defecto 5000) |
|
|
179
|
+
|
|
180
|
+
`openchasqui` solo reemplaza carpetas que él mismo creó; se niega a escribir
|
|
181
|
+
sobre cualquier otra. Ningún entorno puede parecer de producción y un secreto
|
|
182
|
+
nunca lleva valor.
|
|
183
|
+
|
|
184
|
+
## Overlays
|
|
185
|
+
|
|
186
|
+
Un overlay renombra, reagrupa o recorta la colección sin tocar el contrato. Dos
|
|
187
|
+
extensiones controlan la organización:
|
|
188
|
+
|
|
189
|
+
```yaml
|
|
190
|
+
overlay: 1.0.0
|
|
191
|
+
info: { title: Nombres en español, version: 1.0.0 }
|
|
192
|
+
actions:
|
|
193
|
+
- target: $.paths['/banks'].get
|
|
194
|
+
update:
|
|
195
|
+
summary: Listar bancos
|
|
196
|
+
x-openchasqui-folder: Catálogos/Bancos
|
|
197
|
+
x-openchasqui-order: 1
|
|
198
|
+
- target: $.paths['/internal/metrics']
|
|
199
|
+
remove: true
|
|
13
200
|
```
|
|
14
201
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
202
|
+
## Políticas
|
|
203
|
+
|
|
204
|
+
`generate` y `verify` informan:
|
|
205
|
+
|
|
206
|
+
| Regla | Severidad | Cuándo |
|
|
207
|
+
| ------------------------ | ----------- | ---------------------------------------------------------- |
|
|
208
|
+
| `no-secrets-in-examples` | error | Un ejemplo contiene un JWT, una clave de nube o un token |
|
|
209
|
+
| `reserved-email-domains` | advertencia | Un correo de ejemplo no usa `example.com` u otro reservado |
|
|
210
|
+
| `success-response` | advertencia | Una operación no documenta ninguna respuesta 2xx |
|
|
211
|
+
| `public-write` | advertencia | Una operación de escritura no pide autenticación |
|
|
212
|
+
|
|
213
|
+
## Paquetes
|
|
214
|
+
|
|
215
|
+
El CLI instala todo lo necesario; estos son los paquetes que lo forman.
|
|
216
|
+
|
|
217
|
+
<details>
|
|
218
|
+
<summary>Ver los 12 paquetes</summary>
|
|
219
|
+
|
|
220
|
+
| Paquete | Propósito |
|
|
221
|
+
| ----------------------------------------------------------------------------- | --------------------------------------------------- |
|
|
222
|
+
| [`@abitechdev/openchasqui`](https://github.com/abitech-dev/abitech-openchasqui-cli/tree/main/packages/cli) | Línea de comandos |
|
|
223
|
+
| [`@abitechdev/openchasqui-core`](https://github.com/abitech-dev/abitech-openchasqui-cli/tree/main/packages/core) | Pipeline |
|
|
224
|
+
| [`@abitechdev/openchasqui-spec`](https://github.com/abitech-dev/abitech-openchasqui-cli/tree/main/packages/spec) | Modelo canónico y contrato de plugins |
|
|
225
|
+
| [`@abitechdev/openchasqui-plugin-kit`](https://github.com/abitech-dev/abitech-openchasqui-cli/tree/main/packages/plugin-kit) | Utilidades para autores de plugins |
|
|
226
|
+
| [`@abitechdev/openchasqui-transformer-overlay`](https://github.com/abitech-dev/abitech-openchasqui-cli/tree/main/packages/transformer-overlay) | Overlay 1.0 |
|
|
227
|
+
| [`@abitechdev/openchasqui-loader-openapi`](https://github.com/abitech-dev/abitech-openchasqui-cli/tree/main/packages/loader-openapi) | Cargador de OpenAPI 3.0 y 3.1 |
|
|
228
|
+
| [`@abitechdev/openchasqui-generator-examples`](https://github.com/abitech-dev/abitech-openchasqui-cli/tree/main/packages/generator-examples) | Ejemplos sintéticos |
|
|
229
|
+
| [`@abitechdev/openchasqui-generator-tests`](https://github.com/abitech-dev/abitech-openchasqui-cli/tree/main/packages/generator-tests) | Pruebas de contrato |
|
|
230
|
+
| [`@abitechdev/openchasqui-validator-policies`](https://github.com/abitech-dev/abitech-openchasqui-cli/tree/main/packages/validator-policies) | Políticas de seguridad y calidad |
|
|
231
|
+
| [`@abitechdev/openchasqui-emitter-postman`](https://github.com/abitech-dev/abitech-openchasqui-cli/tree/main/packages/emitter-postman) | Postman Collection v2.1 |
|
|
232
|
+
| [`@abitechdev/openchasqui-emitter-bruno`](https://github.com/abitech-dev/abitech-openchasqui-cli/tree/main/packages/emitter-bruno) | Bruno, OpenCollection YAML |
|
|
233
|
+
| [`@abitechdev/openchasqui-data-es-pe`](https://github.com/abitech-dev/abitech-openchasqui-cli/tree/main/packages/data-es-pe) | Datos de prueba peruanos: DNI, RUC, celular, ubigeo |
|
|
234
|
+
|
|
235
|
+
</details>
|
|
236
|
+
|
|
237
|
+
## Hoja de ruta
|
|
238
|
+
|
|
239
|
+
| Versión | Alcance |
|
|
240
|
+
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
241
|
+
| 1.0 | Overlay 1.0, ejemplos y pruebas de contrato, políticas y cobertura, Bruno (OpenCollection) y Postman, `init` y `verify`, datos de prueba peruanos |
|
|
242
|
+
| 1.1 | Flujos Arazzo, GitHub Action, SARIF |
|
|
243
|
+
| 1.2 | `.http` e Insomnia, OpenAPI 3.2 |
|
|
244
|
+
| 2.0 | k6 y Playwright, contrato estable para plugins de terceros |
|
|
245
|
+
|
|
246
|
+
## Contribuir
|
|
247
|
+
|
|
248
|
+
Los issues y pull requests son bienvenidos. Lee primero
|
|
249
|
+
[CONTRIBUTING.md](https://github.com/abitech-dev/abitech-openchasqui-cli/blob/main/CONTRIBUTING.md); los reportes de seguridad van por
|
|
250
|
+
[SECURITY.md](https://github.com/abitech-dev/abitech-openchasqui-cli/blob/main/SECURITY.md).
|
|
18
251
|
|
|
19
|
-
##
|
|
252
|
+
## Licencia
|
|
20
253
|
|
|
21
|
-
Apache
|
|
254
|
+
[Apache License 2.0](https://github.com/abitech-dev/abitech-openchasqui-cli/blob/main/LICENSE). Copyright 2026 The OpenChasqui Authors.
|
package/package.json
CHANGED
|
@@ -1,7 +1,18 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@abitechdev/openchasqui",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "Generate, validate and distribute API collections from OpenAPI.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"openapi",
|
|
7
|
+
"postman",
|
|
8
|
+
"bruno",
|
|
9
|
+
"api-testing",
|
|
10
|
+
"contract-testing",
|
|
11
|
+
"openapi-overlay",
|
|
12
|
+
"cli",
|
|
13
|
+
"peru",
|
|
14
|
+
"openchasqui"
|
|
15
|
+
],
|
|
5
16
|
"license": "Apache-2.0",
|
|
6
17
|
"type": "module",
|
|
7
18
|
"bin": {
|
|
@@ -27,14 +38,15 @@
|
|
|
27
38
|
"directory": "packages/cli"
|
|
28
39
|
},
|
|
29
40
|
"dependencies": {
|
|
30
|
-
"@abitechdev/openchasqui-
|
|
31
|
-
"@abitechdev/openchasqui-
|
|
32
|
-
"@abitechdev/openchasqui-emitter-
|
|
33
|
-
"@abitechdev/openchasqui-
|
|
34
|
-
"@abitechdev/openchasqui-
|
|
35
|
-
"@abitechdev/openchasqui-
|
|
36
|
-
"@abitechdev/openchasqui-
|
|
37
|
-
"@abitechdev/openchasqui-
|
|
38
|
-
"@abitechdev/openchasqui-
|
|
39
|
-
}
|
|
41
|
+
"@abitechdev/openchasqui-core": "^0.1.1",
|
|
42
|
+
"@abitechdev/openchasqui-emitter-postman": "^0.1.1",
|
|
43
|
+
"@abitechdev/openchasqui-emitter-bruno": "^0.1.1",
|
|
44
|
+
"@abitechdev/openchasqui-generator-examples": "^0.1.1",
|
|
45
|
+
"@abitechdev/openchasqui-loader-openapi": "^0.1.1",
|
|
46
|
+
"@abitechdev/openchasqui-generator-tests": "^0.1.1",
|
|
47
|
+
"@abitechdev/openchasqui-validator-policies": "^0.1.1",
|
|
48
|
+
"@abitechdev/openchasqui-spec": "^0.1.1",
|
|
49
|
+
"@abitechdev/openchasqui-transformer-overlay": "^0.1.1"
|
|
50
|
+
},
|
|
51
|
+
"scripts": {}
|
|
40
52
|
}
|