HTTP Request/Response to API Blueprint Formatter

Common errors

• TypeError: bf.format is not a function

  cause This typically occurs if the module was `require`d incorrectly, or if the path to the formatter was wrong, leading to `bf` not being the expected module object with a `format` method.
  fix Ensure you are using `const bf = require('api-blueprint-http-formatter');` and then calling `bf.format(post);`. If requiring from a local file, ensure the path `require('./src/api-blueprint-http-formatter')` is correct relative to your script.

• Error: Cannot find module 'api-blueprint-http-formatter'

  cause The package is not installed or not resolvable by Node.js.
  fix Install the package using npm: `npm install api-blueprint-http-formatter` or ensure it's listed in your `package.json` dependencies and `npm install` has been run.

Warnings

• breaking This package is fundamentally unmaintained, with its last commit in 2014 and a 0.0.1 version. It is unlikely to receive updates for security vulnerabilities, bug fixes, or compatibility with newer Node.js versions or API Blueprint specification changes.
  Fix: Consider migrating to tools that support OpenAPI/Swagger, which is the current industry standard for API description and has robust, actively maintained tooling.
• gotcha The API Blueprint specification, while once popular, has largely been superseded by OpenAPI/Swagger. Many modern API design and documentation tools, including Apiary.io (a former champion of API Blueprint), have either shut down or shifted focus, making API Blueprint a less supported standard.
  Fix: For new projects, prefer using OpenAPI/Swagger. If maintaining existing API Blueprint documentation, be aware of the limited tooling and community support. Tools like `apib2openapi` might help with migration.
• gotcha This package is a CommonJS module and does not natively support ES module (`import`) syntax. Attempting to `import` it directly in an ESM context will result in an error unless a transpilation step or a CommonJS compatibility loader is used.
  Fix: Use `const bf = require('api-blueprint-http-formatter');` for importing this module.
• gotcha The package expects input objects to conform to the HTTP request and response data models used by the Gavel validation tool. Deviations from this precise structure may lead to malformed or incorrect API Blueprint output.
  Fix: Refer to Gavel's documentation for the exact expected `request` and `response` object structures to ensure correct formatting.

Install

• npm install api-blueprint-http-formatter npm
• yarn add api-blueprint-http-formatter yarn
• pnpm add api-blueprint-http-formatter pnpm

Imports

• format
  wrong:

  import { format } from 'api-blueprint-http-formatter';

  correct:

  const formatter = require('api-blueprint-http-formatter').format;

  This package is a CommonJS module. Direct ES module `import` syntax is not supported without a compatibility layer or bundler configuration. The primary export is the `format` function.
• default export
  wrong:

  import bf from 'api-blueprint-http-formatter';

  correct:

  const bf = require('api-blueprint-http-formatter');
  const blueprint = bf.format(post);

  The package exports an object with a `format` method. While you can `require` the module and then access `.format`, it's often clearer to destructure or directly assign the `format` function if it's the only one you need. Direct default ESM imports will not work.
• * as formatter
  wrong:

  import * as formatterModule from 'api-blueprint-http-formatter';

  correct:

  const formatterModule = require('api-blueprint-http-formatter');

  For CommonJS modules, `require` returns the module.exports object. Using `import * as` for a CJS module in an ESM context might work depending on your build setup, but `require` is the intended usage.

Quickstart

Demonstrates how to use the `format` function to convert an HTTP request/response pair into an API Blueprint formatted string.

const bf = require('api-blueprint-http-formatter');

const httpPair = {
  "request": {
    "method": "POST",
    "uri": "/shopping-cart",
    "headers": {
      "User-Agent": "curl/7.24.0",
      "Host": "api.example.com",
      "Accept": "*/*",
      "Content-Type": "application/json",
      "Content-Length": "39"
    },
    "body": "{ \"product\":\"1AB23ORM\", \"quantity\": 2 }"
  },
  "response": {
    "statusCode": "201",
    "statusMessage": "Created",
    "headers": {
      "Content-Type": "application/json",
      "Date": "Sun, 21 Jul 2009 14:51:09 GMT",
      "X-Apiary-Ratelimit-Limit": "120",
      "Content-Length": "50"
    },
    "body": "{ \"status\": \"created\", \"url\": \"/shopping-cart/2\" }"
  }
};

const blueprintOutput = bf.format(httpPair);
console.log(blueprintOutput);