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:

• DescriptionAnnotation
• JSONSchemaAnnotation

Please, consult the schema API documentation.

API documentation

Top-level

• openAPI
• info
• license
• server
• variable
• enum

Operations

• path
• operation
• operationId
• parameter
• allowEmptyValue
• jsonRequest
• jsonResponse
• responseHeaders

General

• description
• summary
• deprecated
• required

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.

Setter of: path, operation

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