An OpenAPI alternative to describe REST APIs for type-safe code generation.
A simple GET endpoint which returns a hello world message.
{
"operations": {
"getMessage": {
"description": "Returns a hello world message",
"method": "GET",
"path": "/hello/world",
"return": {
"schema": {
"$ref": "Hello_World"
}
}
}
},
"definitions": {
"Hello_World": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}const client = new Client()
client.getMessage(): HelloWorld
interface HelloWorld {
message?: string
}
Through the arguments keyword you can map values from the HTTP request to an argument, in this example we map the HTTP query parameters to the startIndex and count argument
{
"operations": {
"getAll": {
"description": "Returns available todo entries",
"method": "GET",
"path": "/todo",
"arguments": {
"startIndex": {
"in": "query",
"schema": {
"type": "integer"
}
},
"count": {
"in": "query",
"schema": {
"type": "integer"
}
}
},
"return": {
"schema": {
"$ref": "Todos"
}
}
}
},
"definitions": {
"Todos": {
"type": "object",
"properties": {
"entries": {
"type": "array",
"items": {
"$ref": "Todo"
}
}
}
},
"Todo": {
"type": "object",
"properties": {
"title": {
"type": "string"
}
}
}
}
}
const client = new Client()
client.getAll(startIndex: number, count: number): Todos
interface Todos {
entries?: Array<Todo>
}
interface Todo {
title?: string
}
In this example we map the HTTP request body to the payload argument
{
"operations": {
"create": {
"description": "Inserts a new todo entry",
"method": "POST",
"path": "/todo",
"arguments": {
"payload": {
"in": "body",
"schema": {
"$ref": "Todo"
}
}
},
"return": {
"schema": {
"$ref": "Message"
}
}
}
},
"definitions": {
"Todo": {
"type": "object",
"properties": {
"title": {
"type": "string"
}
}
},
"Message": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
}
}
}
}
const client = new Client()
client.create(payload: Todo): Message
interface Todo {
title?: string
}
interface Message {
success?: boolean
message?: string
}
Through the throws keyword you can define specific error payloads, the generated client will then also throw an exception in case the server returns such an error code
{
"operations": {
"getMessage": {
"description": "Returns a hello world message",
"method": "GET",
"path": "/hello/world",
"return": {
"schema": {
"$ref": "Hello_World"
}
},
"throws": [{
"code": 500,
"schema": {
"$ref": "Error"
}
}]
}
},
"definitions": {
"Hello_World": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
},
"Error": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
}
}
}
}const client = new Client()
client.getMessage(): HelloWorld throws Error
interface HelloWorld {
message?: string
}
interface Error {
success?: boolean
message?: string
}
Through the dot notation at the operation key you can group your operations into logical units
{
"operations": {
"todo.create": {
"description": "Inserts a new todo entry",
"method": "POST",
"path": "/todo",
"arguments": {
"payload": {
"in": "body",
"schema": {
"$ref": "Todo"
}
}
},
"return": {
"schema": {
"$ref": "Message"
}
}
},
"product.create": {
"description": "Inserts a new product",
"method": "POST",
"path": "/product",
"arguments": {
"payload": {
"in": "body",
"schema": {
"$ref": "Product"
}
}
},
"return": {
"schema": {
"$ref": "Message"
}
}
}
},
"definitions": {
"Todo": {
"type": "object",
"properties": {
"title": {
"type": "string"
}
}
},
"Product": {
"type": "object",
"properties": {
"title": {
"type": "string"
}
}
},
"Message": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
}
}
}
}const client = new Client()
client.todo().create(payload: Todo): Message
client.product().create(payload: Product): Message
interface Todo {
title?: string
}
interface Product {
title?: string
}
interface Message {
success?: boolean
message?: string
}