Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/greeeg/openapi-kit
A set of utilities to generate an API client, types, mocks & react-query hooks for OpenAPI
https://github.com/greeeg/openapi-kit
openapi swagger typescript
Last synced: about 2 months ago
JSON representation
A set of utilities to generate an API client, types, mocks & react-query hooks for OpenAPI
- Host: GitHub
- URL: https://github.com/greeeg/openapi-kit
- Owner: greeeg
- License: mit
- Created: 2023-12-19T07:08:30.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2024-06-21T06:41:10.000Z (7 months ago)
- Last Synced: 2024-11-14T13:45:35.452Z (about 2 months ago)
- Topics: openapi, swagger, typescript
- Language: TypeScript
- Homepage:
- Size: 1.25 MB
- Stars: 5
- Watchers: 2
- Forks: 0
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# OpenAPI kit
[](https://www.npmjs.com/package/openapi-kit)
[](https://www.npmjs.com/package/openapi-kit)
[](https://bundlephobia.com/package/openapi-kit)
> A set of utilities to generate an API client, types, mocks & react-query hooks for OpenAPI
## Features
- Parse OpenAPI 3 & OpenAPI 3.1 YML/JSON documents
- Generate Typescript types for OpenAPI components & paths
- Generate a typed API client with named methods for OpenAPI operations
- Generate mock data for OpenAPI operations
- Generate [`react-query`](https://github.com/TanStack/query) query & mutation hooks for OpenAPI operations
## Getting started
OpenAPI kit comes with a command you can execute to get quickly started.
If the command does not provide enough options for your generation needs, check out the **"Advanced usage"** section to create your own script.
```sh
yarn add -D openapi-kit
# Used by API client
yarn add query-string
# Used by `react-query` hooks
yarn add @tanstack/react-query
```
```json
{
"name": "my-app",
"scripts": {
"openapi": "openapi-kit generate -f ./openapi/pet-store.yml -o ./generated"
}
}
```
## CLI options
```sh
# Specify the OpenAPI spec file path & output directory
openapi-kit generate -f ./openapi/pet-store.yml -o ./generated
# The `prettyOutput` flag ensures the output is formatted using Prettier
openapi-kit generate -f ./openapi/pet-store.yml -o ./generated --prettyOutput
# Only generate type definitions
openapi-kit generate -f ./openapi/pet-store.yml -o ./generated --types
# Only generate type definitions & API client
openapi-kit generate -f ./openapi/pet-store.yml -o ./generated --types --apiClient
# Only generate type definitions & mock data
openapi-kit generate -f ./openapi/pet-store.yml -o ./generated --types --mockData
```
### Using types
```ts
import { Components, Paths } from 'generated/typeDefinitions'
type Pet = Components.Schemas.Pet
const pet: Pet = {
id: 1,
name: 'Paul',
tag: 'happy',
}
const getPetNames = (response: Paths.ListPets.Responses.$200): string[] => {
return response.map((pet) => pet.name)
}
```
### Using API client
```ts
import { getAPIClient } from 'generated/apiClient'
const apiClient = getAPIClient({
baseUrl: 'https://petstore.swagger.io/v2',
headers: {
Accept: 'application/json',
},
onError: (error: unknown) => {
if (error instanceof HTTPRequestError && error.statusCode === 401) {
// Do something
}
},
})
const response = await apiClient.showPetById({
pathParams: {
petId: 1,
},
})
if (response.ok) {
console.log(response.data.name)
}
```
### Using mock data
```tsx
import PetsList from 'components/PetsList'
import { ListPetsResponse$200 } from 'generated/mockData'
const App = () => {
return
}
```
### Using `react-query` hooks
First, update your React App to include two React context providers:
- One for `react-query`
- One for your API client
```tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { APIClientProvider } from 'generated/reactQuery'
const queryClient = new QueryClient()
const App = () => {
return (
)
}
```
Then, use autogenerated queries & mutations in your app pages & components.
```tsx
import { useListPets } from 'generated/reactQuery'
const PetsList = () => {
const { data, isLoading } = useListPets({
pathParams: {
owner: 'John',
},
queryParams: {},
})
if (isLoading || !data) {
return Loading...
}
return (
- {pet.name}
{data.map((pet) => (
))}
)
}
export default PetsList
```
## Advanced usage
OpenAPI kit exports a set of functions you can use in your own scripts to export types in multiple folders or choose to not export `react-query` hooks for example.
```ts
import {
dereferenceDocument,
generateAPIClient,
generateReactQueryHooks,
generateTypeDefinitions,
parseDocument,
} from 'openapi-kit'
const run = () => {
const document = await parseDocument('./pet-store.yml')
if (!document) {
return
}
generateTypeDefinitions(document, { outputFilePath: './client/generated/types.ts' })
generateTypeDefinitions(document, { outputFilePath: './api/generated/types.ts' })
}
run()
```