Lil' Schemy is a cli tool that enables code first schema generation from TypeScript
npm install @starduv/lil-schemyLil' Schemy
"Open-Api, Json-Schemer, input, Typescript, ouput, Beamer"
schemy-config.js. First, you need to indicate which files contain your route handlers by updating schemy-config.js like this...
js
module.exports = {
openApi: {
// ... other stuff
entry: [
// this is an array of globs
"./src/io/api-routes/*/.ts"
],
// ... other stuff
}
}
`
Lil' Schemy will search the files that match the glob patterns you defined. Each invocation of LilPath found will result in the creation of a distinct OpenApi path. The first argument of LilPath is your route handler. It returns your route handler, so you can use it with frameworks like Express. Here's an example:
`TS
app.get('/', LilPath((request, reply): void => {
reply.send();
}, {
method: 'GET',
path: '/',
}));
`
The second argument defines path properties, like method and route path. Lil' Schemy isn't able to detect such things from your framework of choice. Instead it asks you for a lil' help. This is an open source project, maybe someone will add method and route path detection for your framework, who knows. There are other functions and types to learn about in the API section that allow you to specify parameters, responses, and data types for your schema paths.
Examples
There are several examples found in the mock api used for testing.
CLI
Here is the top level documentation. Run the CLI in a terminal to learn more.
`
Usage: lil-schemy [options] [command]
CLI to generate schemas from TypeScript
Options:
-V, --version output the version number
--cwd base dir, for relative paths (default: "/Users/joelrainear-wills/dev/lil-schemy")
-h, --help display help for command
Commands:
init Create default lil-schemy configuration (schemy-config.js)
generate [options] Generate one or more schemas
help [command] display help for command
`
API
$3
LilPath identifies an OpenApi path that needs documentation. All of the other Lil functions and types are used inside of this. It has two parameters:
- fn: A function that serves as a route handler in your application.
- options: An instance of the interface, PathItemOptions.
$3
PathItemOptions is an interface that represents options for an OpenApi path. It has the following properties:
- method: An instance of the enumeration type, OperationMethod.
- path: A string representing the route path.
- tags (optional): An array of strings. Tags are a way to categorize your paths. UI tools often group your paths together by tag.
$3
OperationMethod is an enumeration type that represents an HTTP method. It can be one of the following: 'GET' | 'PUT' | 'POST' | 'DELETE' | 'OPTIONS' | 'HEAD' | 'PATCH' | 'TRACE'.
LilResponse tells Schemy where to begin searching for the response type returned by your route handler. It has two parameters:
ResponseOptions.
ResponseOptions is an interface that represents options for a response. It has the following properties:
#/components/examples/. Schemy assumes you placed the corresponding example in schemy-config.js.
LilBodyParam is a type that represents a body parameter. It has two parameters:
LilHeader is a type that represents a header parameter. It has three parameters:
format.
LilQueryParam is a type that represents a query parameter. It has three parameters:
format.
LilRouteParam is a type that represents a route parameter. It has three parameters:
format.
LilRequiredProp is a type that represents a required property.
LilSub replaces your design time type with a desired schema type:
node:events lives in the file events.d.ts.
TS
// events.d.ts
declare module 'node:events' {
import events = require('events');
export = events;
}
// stream.d.ts
declare module stream {
import { EventEmitter, Abortable } from 'node:events';
// ...
}
// return type of route handler
export interface Resolvable {
stream: LilSub
}
`
$3
format is a type that represents a format. It can be either a StringFormat or a NumberFormat.
$3
NumberFormat is a type that represents a number format. It can be one of the following: int32, int64, float, or double.
$3
StringFormat is a type that represents a string format. It can be one of the following: date-time, time, date, duration, email, idn-email, hostname, idn-hostname, ipv4, ipv6, uuid, uri, uri-reference, uri-template, json-pointer, relative-json-pointer, regex, iri, or iri-reference.
$3
generate is a function that generates schemas, optionally writing schemas to user defined filepaths.
- cwd: The base directory used for relative paths when finding files and resolving modules.
- options: An instance of the interface, LilSchemyOptions.
$3
LilSchemyOptions is a type that represents desired schemas
- openApi (optional): An instance of the type, OpenApiOptions
$3
OpenApiOptions tells Lil' Schemy to generate an OpenApi schema
- base: A user defined OpenApi schema that will overlay the generated schema. The only required field is openapi, which is always version "3.1.0" (for now)
- output (optional): The filepath where Lil' Schemy should write the schema. It will not write the schema without this.
- entry: an array of blob patterns describing the files containing http paths that need schemas.
$3
LilSchemyResult is a type containing the result of schema generation
- openApi An instance of the type OpenApiResult
$3
OpenApiResult contains the resultant schema and a filepath where the schema was written
- schema: The schema as a string
- filepath: The filepath where the schema was written
Programmatic Use
You can use Lil-Schemy from your own module by calling the generate function. Here's an example:
`TS
const config = {
openApi: {
// All values in base take precedence over generated values.
base: {
info: {
title: "My Application",
version: "1.0.0"
},
components: {
securitySchemes: {
oauth2: {
type: "oauth2",
description: "Get a JWT",
flows: {
authorizationCode: {
authorizationUrl: "https://www.myauthservice.come/auth",
tokenUrl: "https://www.myauthservice.come/auth/token",
scopes: {
email: "I know your email address"
}
}
}
}
},
},
security: [
{
oauth2: []
}
]
},
// Glob patterns to modules declaring api paths.
entry: [
"./src/routes/*/.ts"
],
// Where the resultanat OpenApi schema is written.
output: "../dist/public/openapi.json"
}
};
const result = generate(__dirname, config);
console.log("The OpenApi schema was written here: ", result.openApi?.filepath);
console.log("I'll write it to standard output for your convenience...");
console.log(result.openApi?.schema);
``