# @stoplight/http-spec

> ## What is it?

Latest version **7.1.0** (published 2024-06-18) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @stoplight/http-spec
pnpm add @stoplight/http-spec
yarn add @stoplight/http-spec
bun add @stoplight/http-spec
```

## Health

**Score 35/100 (D)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 7.1.0 |
| Published | 2024-06-18 |
| First published | 2019-06-16 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=14.13 |
| Dependencies | 12 |
| Unpacked size | 320.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 20 |
| Author | Stoplight |
| Maintainers | stoplight-devops |

## Links

- npm: https://www.npmjs.com/package/@stoplight/http-spec
- Repository: https://github.com/stoplightio/http-spec
- Homepage: https://github.com/stoplightio/http-spec#readme
- Issues: https://github.com/stoplightio/http-spec/issues
- npm.io page: https://npm.io/package/@stoplight/http-spec

## Dependencies (12)

- [tslib](https://npm.io/package/tslib.md) ^2.6.2
- [lodash](https://npm.io/package/lodash.md) ^4.17.21
- [type-is](https://npm.io/package/type-is.md) ^1.6.18
- [fnv-plus](https://npm.io/package/fnv-plus.md) ^1.3.1
- [openapi3-ts](https://npm.io/package/openapi3-ts.md) ^2.0.2
- [@types/type-is](https://npm.io/package/@types/type-is.md) ^1.6.3
- [@stoplight/json](https://npm.io/package/@stoplight/json.md) ^3.18.1
- [@stoplight/types](https://npm.io/package/@stoplight/types.md) 14.1.0
- [@types/json-schema](https://npm.io/package/@types/json-schema.md) 7.0.11
- [postman-collection](https://npm.io/package/postman-collection.md) ^4.1.3
- [@types/swagger-schema-official](https://npm.io/package/@types/swagger-schema-official.md) ~2.0.22
- [@stoplight/json-schema-generator](https://npm.io/package/@stoplight/json-schema-generator.md) 1.0.2

## Recent versions

- 7.1.0 (latest) — 2024-06-18
- 7.2.0-alpha (alpha) — 2026-10-22
- 6.0.0-beta.1 (beta) — 2023-09-20
- 2.3.0 (canary) — 2019-11-04
- 7.0.3 — 2024-03-06
- 7.0.2 — 2024-01-31
- 7.0.1 — 2023-12-21
- 7.0.0 — 2023-12-12
- 6.0.3 — 2023-11-30
- 6.0.2 — 2023-10-09
- 6.0.1 — 2023-10-03
- 6.0.0 — 2023-09-25
- 5.13.0 — 2023-08-28
- 5.12.2 — 2023-08-17
- 5.12.1 — 2023-08-14
- … 153 more at https://npm.io/package/@stoplight/http-spec/versions

## README

# @stoplight/http-spec

## What is it?

HTTP Spec is yet another, hopefully more pragmatic, attempt to standardise OpenAPI v2, OpenAPI v3, Postman Collections and other HTTP-related specification under a single AST to rule them all (at least in Stoplight).

There have been a lot of other attempts to have a universal specification such as API Elements, API Flow and they all failed for a number of reasons. Some of those have been discussed [here](https://www.youtube.com/watch?v=jn_1lJr-DLY).

## Why build it?

Stoplight needs a way to interact with these documents in a standardized way, and relying on some dying intermediate format does not make that much sense. It's better to accept the sad state of the industry and work on a minimal superset format that can encompass the majority of the use cases.

## How's HTTP Spec formed?

This repository contains *exclusively* converters functions that take OpenAPI v2, OpenAPI v3.x, or Postman Collection documents and transforms them into the [http-spec interface](https://github.com/stoplightio/types/blob/master/src/http-spec.ts).

You can explore the whole structure by looking at the [IHttpService](https://github.com/stoplightio/types/blob/master/src/http-spec.ts#L10) definition and checking out its descendants. You'll probably notice that it resembles a lot the current OpenAPI 3.x specification, and that's on purpose. OpenAPI 3.0 has first support and we gracefully upgrade/downgrade the other specification formats to it.

## How do I write a converter?

If you would like to add support for another API description format, like RAML, follow these steps:

1. Create a new directory in the `src/` directory
2. Create a function that from your input returns an `IHttpService`
3. Let the TypeScript errors guide you while filling out the missing fields (such as Security Schemes, Servers)
4. Create a function that's able to return an array of `IHttpOperation` from your own input
5. Profit

## When should I use `withContext`?

If a given fragment of a document needs to be represented as a standalone node, and as such an id is needed, you should wrap a converter with `withContext`.
`withContext` ensures `parentId` will be set properly to all descendant converters - it's important to call `this.generateId` first, though.

Example:

```ts
import { isPlainObject } from '@stoplight/json';
import type { Optional } from '@stoplight/types';

import { withContext } from './context';
import { isNonNullable } from './guards';
import type { ArrayCallbackParameters, TranslateFunction } from './types';

type Item = {
  id: string;
  value: number;
};

type Object = {
  id: string;
  name: string;
  items: Item[];
};

export const translateItem = withContext<
  TranslateFunction<
    // Oas2TranslateFunction & Oas3TranslateFunction are available too
    Record<string, unknown>, // type of the entire doc, should be skipped whe Oas{2,3} TranslateFunction is used
    ArrayCallbackParameters<[object: unknown]>, // fn parameters, ArrayCallbackParameters is a shorthand
    Optional<Item> // fn return type
  >
>(function (object, index) {
  if (!isPlainObject(object)) return;

  const id = this.generateId(`my-item-${index}`); // can also be any of src/generators.ts like this.generateId.httpQuery({ keyOrName: 'whatever' })
  return {
    id,
    value: index,
  };
});

export const translateObject = withContext<
  TranslateFunction<Record<string, unknown>, [object: unknown], Optional<Object>>
>(function (object) {
  if (!isPlainObject(object)) return;

  const id = this.generateId('my_id'); // can also be any of src/generators.ts like this.generateId.httpQuery({ keyOrName: 'whatever' })
  return {
    id,
    name: 'some-name',
    items: Array.isArray(object.items) ? object.items.map(translateItem, this).filter(isNonNullable) : [],
  };
});
```

## IHttpOperation merger

`src/merge.ts` contains a utility that reduces the list of `IHttpOperation`'s into a minimal set. This tool particularly handy if you have a recorded list of request/response pairs, and you want to infer a specification out of it.

The strategy is the following:
1. group operations by paths
2. for each group:
    1. merge request definitions, headers, query parameters, body schemas
    2. group responses by the code
    3. for each response code:
        1. merge headers, examples, encodings, ...
        2. group contents by media type
        3. for each media type: merge body schemas

### Merging strategy highlights

- Conflicting examples will make the merger relax the constraints. That means e.g. if a header is required in one request and not required in another one then the resulting operation will _not_ require that header to be present.
- Different JSON Schemas are coupled with `anyOf`.
- By default, additionalProperties are permitted.

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