API Documentation Generation

Pashmak includes a built-in command to help you generate OpenAPI 3.0 documentation. This makes it easy to maintain up-to-date API documentation without manual effort.

Configuration

// default.ts
export default {
  ???,
  api_docs: {
    url: getEnv('API_DOC_URL', 'http://localhost:' + getEnv('PORT', '3000') + '/openapi.json'),
    merge_files: [
      path.join(__dirname, '../..', 'private', 'openapi_base.json'),
      path.join(__dirname, '../..', 'private', 'openapi_from_routes.json'),
      path.join(__dirname, '../..', 'private', 'openapi_examples.json'),
      path.join(__dirname, '../..', 'private', 'openapi_user_changes.json'),
    ],
    output: path.join(__dirname, '../..', 'public', 'openapi.json'),
  },
}

Available Commands

the main assistance comes from command line:

# generate a base OpenAPI file
npm run generate apidocs generate-base --output path/to/openapi_base.json

# generate paths from all currently registered routes
npm run generate apidocs generate-from-routes --output path/to/openapi_from_routes.json

# merge files from config (default config path: api_docs)
npm run generate apidocs merge-files

# run full flow: generate-base + generate-from-routes + merge-files
npm run generate apidocs from-all

# run full flow with alternate config path
npm run generate apidocs from-all --config pen_testers.api_docs

Notes:

• generate-from-routes converts route params from :id format to OpenAPI {id} format automatically.
• merge-files and from-all can use --config to target a different config path (for example api_docs_internal).
• --output overrides output path for the selected subcommand.

Registering Actual OpenApi Route

If you want to provide a quick page to view your api documents simply add following to your routes:

router.addRoute(
  ["GET"],
  "/api/docs",
  ApiDocumentation(config.getOrFail("api_docs.url"), "rapidoc"),
);

Currently you can use rapidoc or redoc for rendering.

Creating Examples from Tests

You can use your tests to generate examples for api-docs. To do so, just pass a response object from supertest to saveForApiDoc.

import supertest from "supertest";
import { httpServer } from "@devbro/pashmak/facades";
import { saveForApiDoc } from "./helpers";

const server = httpServer();
const s = supertest(server.getHttpHanlder());

let updateResponse = await s
  .put(`/api/v1/cats/${cat_id}`)
  .set("Authorization", `Bearer ${accessToken}`)
  .send({
    name: "Mainecoon",
    weight: "100KG",
  });

await saveForApiDoc(updateResponse, {
  example_name: "Updating a cat breed details",
  tags: ["Cats"],
  routePath: "/api/v1/cats/:id",
});

The code for this method is part of your project so you can make adjustments as needed. Here are some details to have in mind:

• You can pass name of example and tags to help organize your examples.
• routePath is optional but recommended so examples are attached to the intended endpoint.
• If Authorization header exists, it will automatically mark the endpoint as authentication required.
• It can be beneficial to have tests with apidocs tagged to improve performance of document generation

Generating different apidocs

There may be situations that you want to generate different sets of api-docs. An example of this would be when you want to generate one for public release, another one for internal use, and a third for pen testers. To make this you can create multiple entries in your config file:

// src/config/default.ts
export default {
  ???,
  api_docs: ???,
  api_docs_internal: ???,
  pen_testers: {
    api_docs: ???,
  },
}

once you have different configs, you can run different merge commands:

# use api_docs as default
npm run generate apidocs merge-files

# use api_docs_internal for merge process
npm run generate apidocs merge-files --config api_docs_internal

# use { pen_testers: { api_docs: ??? } } for merge process
npm run generate apidocs merge-files --config pen_testers.api_docs

# or generate everything and merge in one run
npm run generate apidocs from-all --config pen_testers.api_docs

Best practices

Pashmak creates api docs by merging multiple json files into a single api doc file. As a result you can have each portion of the doc created separately.

• Use base api doc to start. it is the fastest way to start with documentations
• Keep different portions of api docs based on how they need to be generated. Examples can be generated independently so have those parts in different parts.
• Opt for statically created api-docs. This way you can control what your end users see and not disclose endpoints that are not meant for external users.
• Use tests to create your examples. This is beneficials to save time in managing api-docs and give actual examples that work!
• Add CI pipelines to run generate apidocs from-all and commit updated api docs.