schema-openapi
Declarative pipe-able API for OpenAPI specification construction using @effect/schema.
🚧 Under development.
Installation
pnpm add schema-openapi
OpenAPI schema derivation from @effect/schema
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:
DescriptionAnnotationJSONSchemaAnnotation
Please, consult the schema API documentation.
API documentation
Top-level
Operations
General
Top-level
import * as OpenApi from 'schema-openapi';openAPI
Use openAPI('Name of you API', 'version') to initialize a new
openAPI specification.
Available setters: info
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
license
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
server
Sets a server section.
OpenApi.openAPI('My API', '2.0.1', OpenApi.server('http://my-production.com'));Available setters: description, variable
Setter of: openAPI
variable
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
enum
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
Operations
path
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
operation
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
parameter
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
parameter
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
tags
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
allowEmptyValue
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
jsonRequest
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
jsonResponse
Set the JSON response specification. The (2nd) schema parameter can be
either undefined or Schema<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
responseHeaders
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
General
description
Sets a description field.
Setter of: info, operation, parameter
summary
Sets a summary field.
deprecated
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
required
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
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "github-actions[bot]")
![renovate[bot] avatar](https://avatars.githubusercontent.com/in/2740?v=4 "renovate[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent