{"id":18447776,"url":"https://github.com/stoplightio/http-spec","last_synced_at":"2026-03-05T20:03:26.429Z","repository":{"id":38630499,"uuid":"192135520","full_name":"stoplightio/http-spec","owner":"stoplightio","description":"Utilities to normalize OpenAPI v2 and v3 objects for the Stoplight ecosystem.","archived":false,"fork":false,"pushed_at":"2024-12-19T14:02:16.000Z","size":1517,"stargazers_count":20,"open_issues_count":22,"forks_count":12,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-03-28T10:54:50.272Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://stoplight.io","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stoplightio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-06-16T00:34:48.000Z","updated_at":"2024-12-19T14:02:18.000Z","dependencies_parsed_at":"2022-07-21T11:32:52.154Z","dependency_job_id":"a7ae55bd-8f3f-42b0-8321-a555f209d77d","html_url":"https://github.com/stoplightio/http-spec","commit_stats":{"total_commits":243,"total_committers":32,"mean_commits":7.59375,"dds":0.7283950617283951,"last_synced_commit":"971bbeee822fb22a203fc002b207f1a8c907641e"},"previous_names":[],"tags_count":164,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stoplightio%2Fhttp-spec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stoplightio%2Fhttp-spec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stoplightio%2Fhttp-spec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stoplightio%2Fhttp-spec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stoplightio","download_url":"https://codeload.github.com/stoplightio/http-spec/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247234923,"owners_count":20905854,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T07:14:24.207Z","updated_at":"2026-03-05T20:03:26.378Z","avatar_url":"https://github.com/stoplightio.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @stoplight/http-spec\n\n## What is it?\n\nHTTP 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).\n\nThere 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).\n\n## Why build it?\n\nStoplight 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.\n\n## How's HTTP Spec formed?\n\nThis 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).\n\nYou 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.\n\n## How do I write a converter?\n\nIf you would like to add support for another API description format, like RAML, follow these steps:\n\n1. Create a new directory in the `src/` directory\n2. Create a function that from your input returns an `IHttpService`\n3. Let the TypeScript errors guide you while filling out the missing fields (such as Security Schemes, Servers)\n4. Create a function that's able to return an array of `IHttpOperation` from your own input\n5. Profit\n\n## When should I use `withContext`?\n\nIf 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`.\n`withContext` ensures `parentId` will be set properly to all descendant converters - it's important to call `this.generateId` first, though.\n\nExample:\n\n```ts\nimport { isPlainObject } from '@stoplight/json';\nimport type { Optional } from '@stoplight/types';\n\nimport { withContext } from './context';\nimport { isNonNullable } from './guards';\nimport type { ArrayCallbackParameters, TranslateFunction } from './types';\n\ntype Item = {\n  id: string;\n  value: number;\n};\n\ntype Object = {\n  id: string;\n  name: string;\n  items: Item[];\n};\n\nexport const translateItem = withContext\u003c\n  TranslateFunction\u003c\n    // Oas2TranslateFunction \u0026 Oas3TranslateFunction are available too\n    Record\u003cstring, unknown\u003e, // type of the entire doc, should be skipped whe Oas{2,3} TranslateFunction is used\n    ArrayCallbackParameters\u003c[object: unknown]\u003e, // fn parameters, ArrayCallbackParameters is a shorthand\n    Optional\u003cItem\u003e // fn return type\n  \u003e\n\u003e(function (object, index) {\n  if (!isPlainObject(object)) return;\n\n  const id = this.generateId(`my-item-${index}`); // can also be any of src/generators.ts like this.generateId.httpQuery({ keyOrName: 'whatever' })\n  return {\n    id,\n    value: index,\n  };\n});\n\nexport const translateObject = withContext\u003c\n  TranslateFunction\u003cRecord\u003cstring, unknown\u003e, [object: unknown], Optional\u003cObject\u003e\u003e\n\u003e(function (object) {\n  if (!isPlainObject(object)) return;\n\n  const id = this.generateId('my_id'); // can also be any of src/generators.ts like this.generateId.httpQuery({ keyOrName: 'whatever' })\n  return {\n    id,\n    name: 'some-name',\n    items: Array.isArray(object.items) ? object.items.map(translateItem, this).filter(isNonNullable) : [],\n  };\n});\n```\n\n## IHttpOperation merger\n\n`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.\n\nThe strategy is the following:\n1. group operations by paths\n2. for each group:\n    1. merge request definitions, headers, query parameters, body schemas\n    2. group responses by the code\n    3. for each response code:\n        1. merge headers, examples, encodings, ...\n        2. group contents by media type\n        3. for each media type: merge body schemas\n\n### Merging strategy highlights\n\n- 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.\n- Different JSON Schemas are coupled with `anyOf`.\n- By default, additionalProperties are permitted.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstoplightio%2Fhttp-spec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstoplightio%2Fhttp-spec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstoplightio%2Fhttp-spec/lists"}