Skip to content

Commit b877338

Browse files
mrlubosmrlubos
authored
Merge pull request #3734 from hey-api/fix/spec-types-2
fix: add WithSpecExtensions type
2 parents ebf6878 + 93311f1 commit b877338

5 files changed

Lines changed: 216 additions & 7 deletions

File tree

‎.changeset/pink-papayas-drop.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@hey-api/spec-types": patch
3+
---
4+
5+
**types**: add `WithSpecExtensions` type

‎packages/spec-types/README.md‎

Lines changed: 193 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
11
<div align="center">
2+
<img alt="Hey API presents openapi-ts" height="214" src="https://heyapi.dev/assets/.gen/openapi-ts-hero-640w.png" width="438">
23
<h1><b>Spec Types</b></h1>
4+
<p>TypeScript definitions for OpenAPI and JSON Schema specifications with complete inline documentation.</p>
35
</div>
46

57
<p align="center">
6-
<!-- <a href="https://www.devtrends.dev/trends?c=v1.kZIBIg"><img src="https://api.devtrends.dev/badge/npm/%40hey-api%2Fopenapi-ts?period=month&style=flat&view=value" alt="DevTrends badge for @hey-api/openapi-ts" /></a> -->
7-
<!-- <a href="https://www.devtrends.dev/trends?c=v1.kZIBIg&v=change"><img src="https://api.devtrends.dev/badge/npm/%40hey-api%2Fopenapi-ts?period=year&style=flat&view=change" alt="DevTrends badge for @hey-api/openapi-ts" /></a> -->
8+
<a href="https://www.devtrends.dev/trends?c=v1.kZIBzQM2"><img src="https://api.devtrends.dev/badge/npm/%40hey-api%2Fspec-types?period=month&style=flat&view=value" alt="DevTrends badge for @hey-api/spec-types" /></a>
9+
<a href="https://www.devtrends.dev/trends?c=v1.kZIBzQM2&v=change"><img src="https://api.devtrends.dev/badge/npm/%40hey-api%2Fspec-types?period=year&style=flat&view=change" alt="DevTrends badge for @hey-api/spec-types" /></a>
810
<a href="https://github.com/hey-api/openapi-ts/actions?query=branch%3Amain"><img src="https://github.com/hey-api/openapi-ts/actions/workflows/ci.yml/badge.svg?event=push&branch=main" alt="CI status" /></a>
911
<a href="https://github.com/hey-api/openapi-ts"><img src="https://img.shields.io/github/stars/hey-api/openapi-ts?style=flat&logo=github&label=GitHub&color=54C82D" alt="GitHub stars" /></a>
1012
<a href="https://github.com/hey-api/openapi-ts/blob/main/LICENSE.md"><img src="https://img.shields.io/github/license/hey-api/openapi-ts" alt="MIT License"></a>
1113
</p>
1214

1315
<p align="center">
14-
<!-- <a href="https://stackblitz.com/edit/hey-api-example?file=openapi-ts.config.ts,src%2Fclient%2Fschemas.gen.ts,src%2Fclient%2Fsdk.gen.ts,src%2Fclient%2Ftypes.gen.ts">Demo</a>
15-
<span>&nbsp;•&nbsp;</span> -->
16-
<!-- <a href="https://heyapi.dev">Manual</a>
17-
<span>&nbsp;•&nbsp;</span> -->
16+
<a href="https://heyapi.dev">Manual</a>
17+
<span>&nbsp;•&nbsp;</span>
1818
<a href="https://github.com/hey-api/openapi-ts/issues">Issues</a>
1919
<span>&nbsp;•&nbsp;</span>
2020
<a href="https://heyapi.dev/openapi-ts/community/contributing">Contribute</a>
@@ -25,3 +25,190 @@
2525
TypeScript definitions for OpenAPI and JSON Schema specifications with complete inline documentation.
2626

2727
Part of the Hey API ecosystem.
28+
29+
## Features
30+
31+
- OpenAPI 2.0 (Swagger), 3.0, and 3.1 specifications
32+
- JSON Schema Draft 4 and Draft 2020-12
33+
- inline JSDoc on every property
34+
- zero runtime footprint, types only
35+
36+
## Contributing
37+
38+
Want to see your code in products used by millions?
39+
40+
Start with our [Contributing](https://heyapi.dev/openapi-ts/community/contributing) guide and release your first feature.
41+
42+
## Sponsors
43+
44+
Hey API is sponsor-funded. If you rely on Hey API in production, consider becoming a [sponsor](https://github.com/sponsors/hey-api) to accelerate the roadmap.
45+
46+
<h3 align="center">Gold</h3>
47+
48+
<table align="center" style="justify-content: center;align-items: center;display: flex;">
49+
<tbody>
50+
<tr>
51+
<td align="center" width="336px">
52+
<p></p>
53+
<p>
54+
<a href="https://kutt.to/pkEZyc" target="_blank">
55+
<picture height="50px">
56+
<source media="(prefers-color-scheme: dark)" srcset="https://heyapi.dev/assets/.gen/stainless-logo-wordmark-480w.jpeg">
57+
<img alt="Stainless logo" height="50px" src="https://heyapi.dev/assets/.gen/stainless-logo-wordmark-480w.jpeg">
58+
</picture>
59+
</a>
60+
<br/>
61+
Best-in-class developer interfaces for your API.
62+
<br/>
63+
<a href="https://kutt.to/pkEZyc" style="text-decoration:none;" target="_blank">
64+
stainless.com
65+
</a>
66+
</p>
67+
<p></p>
68+
</td>
69+
<td align="center" width="336px">
70+
<p></p>
71+
<p>
72+
<a href="https://kutt.to/QM9Q2N" target="_blank">
73+
<picture height="50px">
74+
<source media="(prefers-color-scheme: dark)" srcset="https://heyapi.dev/assets/opencode/logo-light.svg">
75+
<img alt="Opencode logo" height="50px" src="https://heyapi.dev/assets/opencode/logo-dark.svg">
76+
</picture>
77+
</a>
78+
<br/>
79+
The open source coding agent.
80+
<br/>
81+
<a href="https://kutt.to/QM9Q2N" style="text-decoration:none;" target="_blank">
82+
opencode.ai
83+
</a>
84+
</p>
85+
<p></p>
86+
</td>
87+
</tr>
88+
</tbody>
89+
</table>
90+
91+
<h3 align="center">Silver</h3>
92+
93+
<table align="center" style="justify-content: center;align-items: center;display: flex;">
94+
<tbody>
95+
<tr>
96+
<td align="center" width="172px">
97+
<a href="https://kutt.to/skQUVd" target="_blank">
98+
<picture height="40px">
99+
<source media="(prefers-color-scheme: dark)" srcset="https://heyapi.dev/assets/scalar/logo-light.svg">
100+
<img alt="Scalar logo" height="40px" src="https://heyapi.dev/assets/scalar/logo-dark.svg">
101+
</picture>
102+
</a>
103+
<br/>
104+
<a href="https://kutt.to/skQUVd" style="text-decoration:none;" target="_blank">
105+
scalar.com
106+
</a>
107+
</td>
108+
<td align="center" width="172px">
109+
<a href="https://kutt.to/Dr9GuW" target="_blank">
110+
<picture height="40px">
111+
<source media="(prefers-color-scheme: dark)" srcset="https://heyapi.dev/assets/fastapi/logo-light.svg">
112+
<img alt="FastAPI logo" height="40px" src="https://heyapi.dev/assets/fastapi/logo-dark.svg">
113+
</picture>
114+
</a>
115+
<br/>
116+
<a href="https://kutt.to/Dr9GuW" style="text-decoration:none;" target="_blank">
117+
fastapi.tiangolo.com
118+
</a>
119+
</td>
120+
</tr>
121+
</tbody>
122+
</table>
123+
124+
<h3 align="center">Bronze</h3>
125+
126+
<table align="center" style="justify-content: center;align-items: center;display: flex;">
127+
<tbody>
128+
<tr>
129+
<td align="center" width="136px">
130+
<a href="https://kutt.to/YpaKsX" target="_blank">
131+
<picture height="34px">
132+
<source media="(prefers-color-scheme: dark)" srcset="https://heyapi.dev/assets/.gen/kinde-logo-wordmark-dark-480w.webp">
133+
<img alt="Kinde logo" height="34px" src="https://heyapi.dev/assets/.gen/kinde-logo-wordmark-480w.jpeg">
134+
</picture>
135+
</a>
136+
</td>
137+
<td align="center" width="136px">
138+
<a href="https://kutt.to/KkqSaw" target="_blank">
139+
<picture height="34px">
140+
<source media="(prefers-color-scheme: dark)" srcset="https://heyapi.dev/assets/cella/logo-light.svg">
141+
<img alt="Cella logo" height="34px" src="https://heyapi.dev/assets/cella/logo-dark.svg">
142+
</picture>
143+
</a>
144+
</td>
145+
</tr>
146+
</tbody>
147+
</table>
148+
149+
## Installation
150+
151+
You can download `@hey-api/spec-types` from npm using your favorite package manager.
152+
153+
#### npm
154+
155+
```sh
156+
npm add @hey-api/spec-types -D -E
157+
```
158+
159+
#### pnpm
160+
161+
```sh
162+
pnpm add @hey-api/spec-types -D -E
163+
```
164+
165+
#### yarn
166+
167+
```sh
168+
yarn add @hey-api/spec-types -D -E
169+
```
170+
171+
#### bun
172+
173+
```sh
174+
bun add @hey-api/spec-types -D -E
175+
```
176+
177+
## Usage
178+
179+
### OpenAPI
180+
181+
Hover over any property to see its definition from the specification.
182+
183+
```ts
184+
import type { OpenAPIV3_1 } from '@hey-api/spec-types';
185+
186+
const doc = {
187+
openapi: '3.1.2',
188+
info: {
189+
title: 'My OpenAPI document',
190+
version: '1.0.0',
191+
},
192+
} satisfies OpenAPIV3_1.Document;
193+
```
194+
195+
### JSON Schema
196+
197+
Full type coverage for Draft 4 and Draft 2020-12 schemas.
198+
199+
```ts
200+
import type { JSONSchemaDraft2020_12 } from '@hey-api/spec-types';
201+
202+
const doc = {
203+
properties: {
204+
foo: {
205+
type: 'string',
206+
},
207+
},
208+
type: 'object',
209+
} satisfies JSONSchemaDraft2020_12.Document;
210+
```
211+
212+
## License
213+
214+
Released under the [MIT License](https://github.com/hey-api/openapi-ts/blob/main/LICENSE.md).

‎packages/spec-types/package.json‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,27 @@
33
"version": "0.1.0",
44
"description": "📃 TypeScript definitions for OpenAPI and JSON Schema specifications with complete inline documentation.",
55
"keywords": [
6+
"api-types",
67
"definitions",
78
"documentation",
9+
"intellisense",
10+
"jsdoc",
811
"json",
12+
"json-schema",
13+
"json-schema-draft-2020-12",
14+
"json-schema-draft-4",
915
"jsonschema",
1016
"openapi",
17+
"openapi-2.0",
18+
"openapi-3.0",
19+
"openapi-3.1",
20+
"openapi-types",
1121
"schema",
1222
"spec",
1323
"specification",
1424
"swagger",
25+
"swagger-2.0",
26+
"type-definitions",
1527
"types",
1628
"typescript"
1729
],

‎packages/spec-types/src/extensions/spec.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,8 @@
66
export interface SpecExtensions {
77
[extension: `x-${string}`]: unknown;
88
}
9+
10+
/**
11+
* Type utility to wrap any type with specification extensions.
12+
*/
13+
export type WithSpecExtensions<T> = T & SpecExtensions;

‎packages/spec-types/src/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
export type { CodeSampleObject, LinguistLanguages } from './extensions/code-samples';
22
export type { EnumExtensions } from './extensions/enum';
3-
export type { SpecExtensions } from './extensions/spec';
3+
export type { SpecExtensions, WithSpecExtensions } from './extensions/spec';
44
export type * as JSONSchemaDraft4 from './json-schema/draft-4';
55
export type * as JSONSchemaDraft2020_12 from './json-schema/draft-2020-12';
66
export * as JSONSchema from './json-schema/union';

0 commit comments

Comments
 (0)