Laminar Oapi CLI
A CLI for the Open Api implementation for the laminar http server.
Usage
yarn add @ovotech/laminar-cli
Given a OpenAPI config file:
---
openapi: 3.0.0
info:
title: Test
version: 1.0.0
servers:
- url: http://localhost:3333
paths:
'/test':
post:
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/User' }
responses:
'200':
description: A Test Object
content:
application/json:
schema: { $ref: '#/components/schemas/Test' }
get:
responses:
'200':
description: A Test Object
content:
application/json:
schema: { $ref: '#/components/schemas/Test' }
components:
schemas:
User:
additionalProperties: false
properties:
email:
type: string
scopes:
type: array
items:
type: string
required:
- email
Test:
properties:
text:
type: string
user:
$ref: '#/components/schemas/User'
required:
- text
We can run:
yarn laminar api --file examples/api.yaml --output examples/__generated__/api.yaml.ts
Which would convert a given api.yaml
file to a api.yaml.ts
. Any external urls, referenced in it would be downloaded, and any local file references would be loaded as well.
Then you can load the types like this:
import { HttpService, init, jsonOk } from '@ovotech/laminar';
import { join } from 'path';
import { openApiTyped } from './__generated__/api.yaml';
const main = async () => {
const listener = await openApiTyped({
api: join(__dirname, 'api.yaml'),
paths: {
'/test': {
post: async ({ body }) => jsonOk({ text: 'ok', user: body }),
get: async () => jsonOk({ text: 'ok', user: { email: 'me@example.com' } }),
},
},
});
const server = new HttpService({ listener });
await init({ initOrder: [server], logger: console });
};
main();
Watching for changes
You can also watch for changes and regenerate the typescript types with the --watch
flag
yarn laminar --watch --file examples/api.yaml --output examples/__generated__/api.yaml.ts
When you update the source yaml file, or any of the local files it references, laminar
would rebuild the typescript files.
Axios type generation
Then given this OpenApi file:
---
openapi: 3.0.0
info:
title: Test
version: 1.0.0
servers:
- url: https://simple.example.com
paths:
'/test/{id}':
parameters:
- name: id
in: path
schema:
type: string
required: true
post:
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/User' }
responses:
'200':
description: A Test Object
content:
application/json:
schema: { $ref: '#/components/schemas/Test' }
get:
responses:
'200':
description: A Test Object
content:
application/json:
schema: { $ref: '#/components/schemas/Test' }
components:
schemas:
User:
additionalProperties: false
properties:
email:
type: string
scopes:
type: array
items:
type: string
required:
- email
Test:
properties:
text:
type: string
user:
$ref: '#/components/schemas/User'
required:
- text
You can run
yarn laminar axios --file examples/axios.yaml --output examples/__generated__/axios.yaml.ts
And would then have:
import { AxiosRequestConfig, AxiosInstance, AxiosResponse } from 'axios';
/**
* Test
*
* Version: 1.0.0
*/
export const axiosOapi = (api: AxiosInstance): AxiosOapiInstance => ({
'POST /test/{id}': (id, data, config) => api.post<Test>(`/test/${id}`, data, config),
'GET /test/{id}': (id, config) => api.get<Test>(`/test/${id}`, config),
api: api,
});
export interface User {
email: string;
scopes?: string[];
}
export interface Test {
text: string;
user?: User;
[key: string]: unknown;
}
export interface AxiosOapiInstance {
'POST /test/{id}': (id: string, data: User, config?: AxiosRequestConfig) => Promise<AxiosResponse<Test>>;
'GET /test/{id}': (id: string, config?: AxiosRequestConfig) => Promise<AxiosResponse<Test>>;
api: AxiosInstance;
}
And you can then use it like this:
import axios from 'axios';
import { axiosOapi } from './__generated__/axios.yaml';
import * as nock from 'nock';
/**
* Mock the simple rest api so we can test it out
*/
nock('http://simple.example.com')
.get('/test/20')
.reply(200, { text: 'test' })
.post('/test/30')
.reply(200, { text: 'test', user: { email: 'test@example.com' } });
/**
* Wrap an axios instance. This will add typed functions with the name of the paths
*/
const simple = axiosOapi(axios.create({ baseURL: 'http://simple.example.com' }));
simple['GET /test/{id}']('20').then(({ data }) => console.log(data));
simple['POST /test/{id}']('30', { email: 'test2example.com' }).then(({ data }) => console.log(data));
Complex example
If we use swagger's petstore.json example, we can generate the petstore types and use them like this:
import { axiosOapi } from './__generated__/petstore.json';
import axios from 'axios';
const petstore = axiosOapi(axios.create({ baseURL: 'https://petstore.swagger.io/v2' }));
const main = async () => {
const { data: pixel } = await petstore['PUT /pet']({
name: 'Pixel',
photoUrls: ['https://placekitten.com/g/200/300'],
tags: [{ name: 'axios-oapi-cli' }],
});
console.log('SAVED', pixel);
const { data: retrievedPixel } = await petstore['GET /pet/{petId}'](pixel.id!);
console.log('RETRIEVED', retrievedPixel);
// Use the underlying api to perform custom requests
const { data: inventory } = await petstore.api.get('/store/inventory');
console.log('INVENTORY', inventory);
};
main();
STDIN / STDOUT and piping
If you don't include "output" the cli will output to stdout. You can use this to chain with other processors like prettier
yarn laminar axios --file examples/simple.yaml | prettier --stdin-filepath examples/simple.types.ts > examples/simple.types.ts
If you omit the "file" option, stdin will be used. This can be used to pipe the file contents from somewhere else (like curl). By default it will asume the content to be json.
curl http://example.com/simple.json | yarn laminar axios --output examples/simple.types.ts
You can specify that the openapi content is yaml too:
curl http://example.com/simple.yaml | yarn laminar axios --output examples/simple.types.ts --stdin-type yaml
Running the tests
You can run the tests with:
yarn test
Coding style (linting, etc) tests
Style is maintained with prettier and eslint
yarn lint
Deployment
Deployment is preferment by yarn automatically on merge / push to main, but you'll need to bump the package version numbers yourself. Only updated packages with newer versions will be pushed to the npm registry.
Contributing
Have a bug? File an issue with a simple example that reproduces this so we can take a look & confirm.
Want to make a change? Submit a PR, explain why it's useful, and make sure you've updated the docs (this file) and the tests (see test folder).
License
This project is licensed under Apache 2 - see the LICENSE file for details