0.4.1 • Published 2 years ago
@caviajs/http-contract v0.4.1
Introduction
Contract, based on the scheme, converts and validates the request and response payload. It also has the ability to generate an HTTP client.
Usage
Installation
npm install @caviajs/http-contract --save
Configure the interceptor
import { HttpContract } from '@caviajs/http-contract';
import { Interceptor } from '@caviajs/http-router';
export const HttpContractInterceptor: Interceptor = HttpContract.setup();
Bind the interceptor
httpRouter
.intercept(HttpContractInterceptor);
Setup contract route
The contract route is needed to provide the specification on the basis of which the contract will be generated.
httpRouter
.route({
handler: () => httpRouter.specification,
method: 'GET',
path: '/meta/contract',
});
Setup contract metadata in routes
httpRouter
.route({
handler: (request, response) => {
// request.body
// request.headers
// request.params
// request.query
// ...
},
metadata: {
contract: {
// ...
},
},
method: 'POST',
path: '/guinea-pigs',
});
metadata.contract.description
httpRouter
.route({
// ...
metadata: {
contract: {
/*
description: string;
*/
},
},
});
metadata.contract.name
The name is the unique name of the router from which the CLI generates the HTTP client.
httpRouter
.route({
// ...
metadata: {
contract: {
/*
name: string;
*/
},
},
});
metadata.contract.request.body
Using this schema you can try to convert and validate the request body for specific mime-types.
httpRouter
.route({
handler: (request, response) => {
// request.body ...
},
metadata: {
contract: {
request: {
/*
body: {
'application/json'?: SchemaArray | SchemaBoolean | SchemaBuffer | SchemaNumber | SchemaObject | SchemaStream;
'application/octet-stream'?: SchemaBuffer | SchemaStream;
'application/pdf'?: SchemaBuffer | SchemaStream;
'application/x-www-form-urlencoded'?: SchemaBuffer | SchemaStream | SchemaObject;
'application/xml'?: SchemaBuffer | SchemaStream | SchemaString;
'image/gif'?: SchemaBuffer | SchemaStream;
'image/jpeg'?: SchemaBuffer | SchemaStream;
'image/png'?: SchemaBuffer | SchemaStream;
'image/tiff'?: SchemaBuffer | SchemaStream;
'multipart/form-data'?: SchemaBuffer | SchemaStream;
'text/css'?: SchemaBuffer | SchemaStream | SchemaString;
'text/csv'?: SchemaBuffer | SchemaStream | SchemaString;
'text/html'?: SchemaBuffer | SchemaStream | SchemaString;
'text/plain'?: SchemaBuffer | SchemaStream | SchemaString;
'video/mp4'?: SchemaBuffer | SchemaStream;
}
*/
},
},
},
/* ... */
});
metadata.contract.request.headers
Using this schema you can validate the request headers.
httpRouter
.route({
handler: (request, response) => {
// request.headers ...
},
metadata: {
contract: {
request: {
/*
headers: {
[name: string]: SchemaEnum | SchemaString;
}
*/
},
},
},
/* ... */
});
metadata.contract.request.params
Using this schema you can try to convert and validate the request params.
httpRouter
.route({
handler: (request, response) => {
// request.params ...
},
metadata: {
contract: {
request: {
/*
params: {
[name: string]: SchemaBoolean | SchemaEnum | SchemaNumber | SchemaString;
}
*/
},
},
},
/* ... */
});
metadata.contract.request.query
Using this schema you can try to convert and validate the request query.
httpRouter
.route({
handler: (request, response) => {
// request.query ...
},
metadata: {
contract: {
request: {
/*
query: {
[name: string]: SchemaBoolean | SchemaEnum | SchemaNumber | SchemaString;
}
*/
},
},
},
/* ... */
});
metadata.contract.responsesstatus.body
httpRouter
.route({
handler: (request, response) => {
response.statusCode = 200;
// return ...
},
metadata: {
contract: {
responses: {
200: {
/*
body: SchemaArray | SchemaBoolean | SchemaBuffer | SchemaEnum | SchemaNumber | SchemaObject | SchemaStream | SchemaString;
*/
},
},
},
},
/* ... */
});
metadata.contract.responsesstatus.headers
httpRouter
.route({
handler: (request, response) => {
response.statusCode = 200;
response.setHeader('name', 'value');
// ...
},
metadata: {
contract: {
responses: {
200: {
/*
headers: {
[name: string]: SchemaEnum | SchemaString;
}
*/
},
},
},
},
/* ... */
});
Generate a contract based on specification
generate-contract --url http://localhost:3000/meta/contract --output src/contracts/foo