# schema-openapi

> Pipeable API for OpenAPI specification and @effect/schema compilers

Latest version **0.39.1** (published 2024-06-21) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install schema-openapi
pnpm add schema-openapi
yarn add schema-openapi
bun add schema-openapi
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 0.39.1 |
| Published | 2024-06-21 |
| First published | 2023-04-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 236.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 16 |
| Author | Milan Suk |

## Links

- npm: https://www.npmjs.com/package/schema-openapi
- Repository: https://github.com/sukovanej/schema-openapi
- Homepage: https://github.com/sukovanej/schema-openapi#readme
- Issues: https://github.com/sukovanej/schema-openapi/issues
- npm.io page: https://npm.io/package/schema-openapi

## Recent versions

- 0.39.1 (latest) — 2024-06-21
- 0.39.0 — 2024-06-19
- 0.38.3 — 2024-06-08
- 0.38.2 — 2024-05-20
- 0.38.1 — 2024-05-10
- 0.38.0 — 2024-05-10
- 0.37.2 — 2024-04-30
- 0.37.1 — 2024-04-23
- 0.37.0 — 2024-04-20
- 0.36.0 — 2024-04-16
- 0.35.1 — 2024-04-16
- 0.35.0 — 2024-04-15
- 0.34.6 — 2024-04-10
- 0.34.5 — 2024-04-04
- 0.34.4 — 2024-04-02
- … 127 more at https://npm.io/package/schema-openapi/versions

## README

# schema-openapi

Declarative pipe-able API for OpenAPI specification construction using
[@effect/schema](https://github.com/effect-ts/schema).

:construction: **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](https://effect-ts.github.io/schema/modules/Schema.ts.html#annotationoptions-type-alias).

# API documentation

Top-level

- [openAPI](#openAPI)
- [info](#info)
- [license](#license)
- [server](#license)
- [variable](#variable)
- [enum](#enum)

Operations

- [path](#path)
- [operation](#operation)
- [operationId](#parameter)
- [parameter](#parameter)
- [allowEmptyValue](#allowEmptyValue)
- [jsonRequest](#jsonRequest)
- [jsonResponse](#jsonResponse)
- [responseHeaders](#responseHeaders)

General

- [description](#description)
- [summary](#summary)
- [deprecated](#deprecated)
- [required](#required)

## Top-level

```typescript
import * as OpenApi from 'schema-openapi';
```

### `openAPI`

Use `openAPI('Name of you API', 'version')` to initialize a new
openAPI specification.

_Available setters_: [info](#info)

### `info`

Sets info section of the specification.

```typescript
OpenApi.openAPI(
  'My API',
  '2.0.1',
  OpenApi.info(OpenApi.description('This is my awesome API'))
);
```

_Available setters_: [description](#description), [license](#license),
[server](#server)

_Setter of_: [openAPI](#openAPI)

### `license`

Sets a license in the info section.

```typescript
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](#info)

### `server`

Sets a server section.

```typescript
OpenApi.openAPI('My API', '2.0.1', OpenApi.server('http://my-production.com'));
```

_Available setters_: [description](#description), [variable](#variable)

_Setter of_: [openAPI](#openAPI)

### `variable`

Adds a variable to the server section.

```typescript
OpenApi.openAPI(
  'My API',
  '2.0.1',
  OpenApi.server(
    'http://my-production:{port}.com',
    OpenApi.variable('port', '3000')
  )
);
```

_Available setters_: [description](#description), [enum](#enum)

_Setter of_: [server](#server)

### `enum`

Adds possible values of a server variable.

```typescript
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](#variable)

## Operations

### `path`

Add a new path.

```typescript
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](#description), [operation](#operation)

_Setter of_: [openAPI](#openAPI)

### `operation`

Set operation. Method name can be one of `get`, `put`, `post`, `delete`,
`options`, `head`, `patch`, `trace`.

```typescript
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](#description), [parameter](#parameter),
[jsonResponse](#jsonResponse), [jsonRequest](#jsonRequest),
[deprecated](#deprecated), [operationId](#parameter)

_Setter of_: [path](#path)

### `parameter`

Set a parameter. The (second) `in` parameter is one of `query`, `header`,
`path`, `cookie`. If the `in` is `path`, [required](#required) must be set
for the parameter.

Set the operation id using `OpenApi.operationId`.

```typescript
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](#operation)

### `parameter`

Set a parameter. The (second) `in` parameter is one of `query`, `header`,
`path`, `cookie`. If the `in` is `path`, [required](#required) must be set
for the parameter.

```typescript
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](#required), [description](#description),
[deprecated](#deprecated), [allowEmptyValue](#allowEmptyValue)

_Setter of_: [operation](#operation)

### `tags`

Set tags for an operation.

```typescript
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](#operation)

### `allowEmptyValue`

Configures the parameter.

```typescript
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](#parameter)

### `jsonRequest`

Set the JSON request body specification.

```typescript
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](#description), [required](#required)

_Setter of_: [operation](#operation)

### `jsonResponse`

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.

```typescript
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](#description), [responseHeaders](#responseHeaders)

_Setter of_: [operation](#operation)

### `responseHeaders`

Set the response headers.

```typescript
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](#jsonResponse)

## General

### `description`

Sets a description field.

_Setter of_: [info](#info), [operation](#operation), [parameter](#parameter)

### `summary`

Sets a summary field.

_Setter of_: [path](#path), [operation](#operation)

### `deprecated`

Sets the spec as deprecated.

```typescript
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](#path), [operation](#operation), [parameter](#parameter)

### `required`

Sets the parameter as required.

```typescript
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](#parameter), [jsonRequest](#jsonRequest)

---
_Source: https://npm.io/package/schema-openapi · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._