wapi-open-api-generator

A tool to generate OpenAPI specifications from Wapi Routes in TypeScript files.

Installation

You don't need to install the package globally. You can use npx to run the command directly.

Usage

To generate OpenAPI specifications, run:

`` bash
npx @creator.co/wapi-open-api-generator
`

To generate only OpenAPI specifications, run: (which use for OpenMCP)

` bash
npx @creator.co/wapi-open-api-generator --only-openapi
`

This command will:

1. Recursively find all router.ts files in the src directory.
2. Extract Wapi Routes from these files.
3. Generate OpenAPI components and save them to ./docs/api.yaml.

Requirements

Ensure your project meets the following requirements:

1. TypeScript files Wapi exported Router, named router.ts.
2. A base.json file in the docs folder.

Configuration

The base.json file should contain your OpenAPI base configuration. Here is an example:

`json
{
"contact": {
"email": "devteam@creator.co",
"name": "Creator.co",
"url": "http://creator.co"
},
"servers": [
{
"url": "http://localhost:8080",
"description": "Local server"
},
{
"url": "https://analytics.dev.creator.co",
"description": "Dev server"
}
],
"security": {
"UserAuth": {
"bearerFormat": "JWT",
"description": "User custom JSON web token.",
"scheme": "bearer",
"type": "http"
},
"APIKey": {
"description": "API Key",
"type": "apiKey",
"in": "header",
"name": "apiKey"
}
}
}
`

Examples

$3

` typescript
import { Route, HttpMethod, Response } from '@creator.co/wapi'

import {
AgenciesListInputType,
AgenciesListInputSchema,
AgenciesResponseType,
AgenciesResponseSchema,
} from './types.js'
import Identity from '../../core/Identity.js'

interface PostRouteType extends Route {}
export default class Post implements PostRouteType {
public path: string = '/agencies'
public method: HttpMethod = HttpMethod.POST
public inputSchema = AgenciesListInputSchema
public openApi = {
summary: 'List Agencies',
description: 'Paginated Agencies Listing',
outputSchema: AgenciesResponseSchema,
tags: ['Agencies'],
security: [{ UserAuth: [] }],
}
public handler: PostRouteType['handler'] = async transaction => {
return await new Identity.Core(transaction, Identity.Globals.AccessLevel.ADMIN).authenticate(
async core => {
const b = transaction.request.getBody()
const resp = await core.agencyService!.agency.list(b.nextToken || undefined)
if (resp instanceof Response) return resp
return Response.SuccessResponse(resp)
}
)
}
}
`

$3

` typescript
// Input Body Example
import { extendZodWithOpenApi } from '@asteasolutions/zod-to-openapi'
import { z } from 'zod'

import { AgencyEntity } from '../../core/components/database/entities/Agency.js'

extendZodWithOpenApi(z)

/ Post /
export const AgenciesListInputSchema = z
.object({
nextToken: z.string().nullish().openapi({
description: 'Optional next token',
}),
})
.openapi({
description: 'Agencies list input body',
name: 'AgenciesListInput',
})

export type AgenciesListInputType = z.infer
`

$3

` typescript

// Output Body Example
import { extendZodWithOpenApi } from '@asteasolutions/zod-to-openapi'
import { z } from 'zod'

import { AgencyEntity } from '../../core/components/database/entities/Agency.js'

extendZodWithOpenApi(z)

/ Post /
export const AgenciesResponseSchema = z
.object({
agencies: z.array(AgencyEntity).openapi({
description: 'List of agencies',
}),
nextToken: z.string().optional().openapi({
description: 'Next token for pagination',
}),
})
.openapi({
description: 'Agencies list response body',
name: 'AgenciesResponse',
})

export type AgenciesResponseType = z.infer
`

$3

` typescript

// Path Parameter Example
import { extendZodWithOpenApi } from '@asteasolutions/zod-to-openapi'
import { z } from 'zod'

import { AgencyEntity } from '../../core/components/database/entities/Agency.js'

extendZodWithOpenApi(z)

/ Path /
export const AgencyPathSchema = z
.object({
agencyId: z.string().openapi({
param: {
name: 'agencyId',
in: 'path',
},
example: 'Agency Id',
}),
})
.openapi({
description: 'Agency authorized route path parameters',
})

export type AgencyPathType = z.infer
``