Declarative pipe-able API for OpenAPI specification construction using @effect/schema.
๐ง Under development.
pnpm add schema-openapi
The heart of this library is a compiler that derives an OpenAPI schema
from an effect-ts Schema
declaration. Generated schema can be adjusted
using annotations. Following annotations are supported:
DescriptionAnnotation
JSONSchemaAnnotation
Please, consult the schema API documentation.
Top-level
Operations
General
import * as OpenApi from 'schema-openapi';
Use openAPI('Name of you API', 'version')
to initialize a new
openAPI specification.
Available setters: info
Sets info section of the specification.
OpenApi.openAPI(
'My API',
'2.0.1',
OpenApi.info(OpenApi.description('This is my awesome API'))
);
Available setters: description, license, server
Setter of: openAPI
Sets a license in the info section.
OpenApi.openAPI(
'My API',
'2.0.1',
OpenApi.info(
OpenApi.description('This is my awesome API'),
OpenApi.license('MIT', 'http://license-url')
)
);
Setter of: info
Sets a server section.
OpenApi.openAPI('My API', '2.0.1', OpenApi.server('http://my-production.com'));
Available setters: description, variable
Setter of: openAPI
Adds a variable to the server section.
OpenApi.openAPI(
'My API',
'2.0.1',
OpenApi.server(
'http://my-production:{port}.com',
OpenApi.variable('port', '3000')
)
);
Available setters: description, enum
Setter of: server
Adds possible values of a server variable.
OpenApi.openAPI(
'My API',
'2.0.1',
OpenApi.server(
'http://my-production:{port}.com',
OpenApi.variable('port', '3000', OpenApi.enum('3000', '3001'))
)
);
Setter of: variable
Add a new path.
OpenApi.openAPI(
'My API',
'2.0.1',
OpenApi.path(
'/pet',
OpenApi.operation(
'get',
OpenApi.jsonResponse('200', S.string, 'Returns a pet')
)
),
OpenApi.path(
'/note',
OpenApi.operation(
'get',
OpenApi.jsonResponse('200', S.string, 'Returns a note')
)
)
);
Available setters: description, operation
Setter of: openAPI
Set operation. Method name can be one of get
, put
, post
, delete
,
options
, head
, patch
, trace
.
OpenApi.openAPI(
'My API',
'2.0.1',
OpenApi.path(
'/pet',
OpenApi.operation(
'get',
OpenApi.jsonResponse('200', S.string, 'Returns a pet')
),
OpenApi.operation(
'post',
OpenApi.jsonRequest(S.struct({ value: S.number })),
OpenApi.jsonResponse('200', S.string, 'Returns a pet')
)
)
);
Available setters: description, parameter, jsonResponse, jsonRequest, deprecated, operationId
Setter of: path
Set a parameter. The (second) in
parameter is one of query
, header
,
path
, cookie
. If the in
is path
, required must be set
for the parameter.
Set the operation id using OpenApi.operationId
.
OpenApi.openAPI(
'My API',
'2.0.1',
OpenApi.path(
'/pet/{id}',
OpenApi.operation(
'get',
OpenApi.jsonResponse('200', S.struct({ value: S.number }), 'Returns a pet')
OpenApi.parameter('id', 'path', S.number, OpenApi.required),
OpenApi.parameter('name', 'query', S.string),
OpenApi.operationId('getPet')
)
)
);
Setter of: operation
Set a parameter. The (second) in
parameter is one of query
, header
,
path
, cookie
. If the in
is path
, required must be set
for the parameter.
OpenApi.openAPI(
'My API',
'2.0.1',
OpenApi.path(
'/pet/{id}',
OpenApi.operation(
'get',
OpenApi.jsonResponse('200', S.struct({ value: S.number }), 'Returns a pet')
OpenApi.parameter('id', 'path', S.number, OpenApi.required),
OpenApi.parameter('name', 'query', S.string),
)
)
);
Available setters: required, description, deprecated, allowEmptyValue
Setter of: operation
Set tags for an operation.
OpenApi.openAPI(
'My API',
'2.0.1',
OpenApi.path(
'/pet/{id}',
OpenApi.operation(
'get',
OpenApi.jsonResponse('200', S.struct({ value: S.number }), 'Returns a pet')
OpenApi.parameter('id', 'path', S.number, OpenApi.required),
OpenApi.parameter('name', 'query', S.string),
OpenApi.tags('Pets')
)
)
);
Setter of: operation
Configures the parameter.
OpenApi.openAPI(
'My API',
'2.0.1',
OpenApi.path(
'/pet/{id}',
OpenApi.operation(
'get',
OpenApi.jsonResponse('200', S.struct({ value: S.number }), 'Returns a pet')
OpenApi.parameter('id', 'path', S.number, OpenApi.required),
OpenApi.parameter('name', 'query', S.string, OpenApi.allowEmptyValue),
)
)
);
Setter of: parameter
Set the JSON request body specification.
OpenApi.openAPI(
'My API',
'2.0.1',
OpenApi.path(
'/pet/{id}',
OpenApi.operation(
'post',
OpenApi.jsonResponse(
'200',
S.struct({ value: S.number }),
'Returns a pet'
),
OpenApi.jsonRequest(S.struct({ value: S.number }))
)
)
);
Available setters: description, required
Setter of: operation
Set the JSON response specification. The (2nd) schema parameter can be
either undefined
or Schema<R, I, O>
. If it's set to undefined
, the
content
field of the response is ommited.
OpenApi.openAPI(
'My API',
'2.0.1',
OpenApi.path(
'/pet/{id}',
OpenApi.operation(
'post',
OpenApi.jsonResponse(
'200',
S.struct({ value: S.number }),
'Returns a pet'
)
)
)
);
Available setters: description, responseHeaders
Setter of: operation
Set the response headers.
OpenApi.openAPI(
'My API',
'2.0.1',
OpenApi.path(
'/pet/{id}',
OpenApi.operation(
'post',
OpenApi.jsonResponse(
'200',
S.struct({ value: S.number }),
'Returns a pet',
OpenApi.responseHeaders({ 'My-Header': S.string })
)
)
)
);
Setter of: jsonResponse
Sets a description field.
Setter of: info, operation, parameter
Sets a summary field.
Sets the spec as deprecated.
OpenApi.openAPI(
'My API',
'2.0.1',
OpenApi.path(
'/pet/{id}',
OpenApi.operation(
'get',
OpenApi.jsonResponse(
'200',
S.struct({ value: S.number }),
'Returns a pet'
),
OpenApi.parameter('name', 'query', S.string, OpenApi.deprecated),
OpenApi.deprecated
),
OpenApi.deprecated
)
);
Setter of: parameter, operation, parameter
Sets the parameter as required.
OpenApi.openAPI(
'My API',
'2.0.1',
OpenApi.path(
'/pet/{id}',
OpenApi.operation(
'post',
OpenApi.jsonRequest(S.struct({ value: S.number }), OpenApi.required),
OpenApi.jsonResponse(
'201',
S.struct({ value: S.literal('success') }),
'Returns a pet'
),
OpenApi.parameter('name', 'path', S.string, OpenApi.required)
)
)
);
Setter of: parameter, jsonRequest