TypeScript module for automatically loading and documenting express endpoints.
The package can be installed via NPM:
$ npm install express-doc-router
The documentation-generation is based on the OpenAPI V3 Specification:
Endpoints should export a router object:
import express from "express";
const router = express.Router();
// ... endpoint logic
export default Router;
Endpoints and routes created in the above format can then be automatically loaded from a specified directory:
import express from "express";
// import the router
import {AutoRouter} from "express-doc-router";
// standard express app
const app = express();
// intialize the router
// here assuming the routes are in src/routes
const autoRouter = new AutoRouter(__dirname, "../src/routes", ".ts", "./routes");
// in an async block
(async () => {
// tell express to forward all routes on /api to the AutoRouter
app.use("/api", await autoRouter.generate());
app.listen(8000, () => {});
})();
The information from the loaded routes can be used to automatically generate documentation:
// ... continiung from the previous example
// import the OpenAPI specification generator
import {SpecificationGenerator} from "express-doc-router";
// setup the generator
const specGenerator = new SpecificationGenerator(
// pass our router
autoRouter,
// pass any mongoDB schemas to be used in the documentation
// format {name: mongoose.Model}
{User: myUserModel},
// set initial configuration for the documentation such as title, version, ...
// see OpenAPI specification for more properties
{
info: {
title: "My API",
version: "1.2.3",
description: "This is the documentation for my API"
},
servers : [
{
url : "http://localhost:8000/api/",
description: "Local test server"
},
{
url: "http://deployment.com/api/",
description: "Deployed server"
}
]
}
);
// generate the specification
const specification = specGenerator.generate();
The generated specification can either be exported or directly used by tools such as swagger-ui-express:
// example with swagger-ui-express
import swaggerUi from "swagger-ui-express";
app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(specification));
The automatically generated documentation is relatively un-detailed, whilst the OpenAPI Specification supports a wide variety of other properties.
More information about an endpoint can be added using the meta
middleware:
// import the meta-middlerware
import {meta} from "express-doc-router";
// example endpoint, as in "Setting up endpoints" above
router.get("/:some_param",
(req, res) => {
// ... does something
res.send(418).end();
}, meta({
// add metadata in the format of an OpenAPI Operation Object
// example:
description: "this is a custom description",
summary: "get endpoint test",
parameters: [
{
name: "some_param",
description: "some description",
required: true,
in: "path"
}
],
responses: {
"200": {
description: "yep, a test response",
content: {
"text/plain": {
example: "test"
}
}
}
}
})
);
This metadata is automatically read by the SpecificationGenerator
and inserted into the finished specification.
OpenAPI Specification types are referenced from openapi-types
.
Class for automatically loading Routes from a folder.
Base for relative paths is __dirname
, so most likely the compiled version of your index.ts
or main script.
AutoRouter.constructor(
dirname: string, -- should always be __dirname of the caller
twd: string, -- folder of the .ts routes, such as ../src/routes
ext: string, -- file extension of the routes, normally .ts
out: string, -- folder containing the compiled routes, such as ./routes
logCreation: boolean -- if loaded routes should be output to the console for debug purposes
)
AutoRouter.generate() : Promise<express.Router> -- generate the routes and return a router
Express middleware for adding additional metadata to and endpoint, should be used with <router>.<method>(<path>, <other handlers>, meta({ ... }))
.
meta(
metadata: OpenAPIV3_1.OperationObject -- the metadata to be injected into the specification
) : express.Handler
MetaRouter
is an extension of express.Router
to allow adding metadata at router level (Path Item
in specification).
It adds a .meta()
function, which can be called same as .get()
, .post()
, .delete()
, ...
MetaRouter.meta(
metadata: OpenAPIV3_1.PathItemObject -- metadata to be injected into the specification
)
Class for generating an OpenAPI V3 Specification using an AutoRouter
.
Schemas are inserted under specification.components.schemas
, as the specification requests.
SpecificationGenerator.constructor(
autoRouter: autoRouter, -- autoRouter to use for generation
schemas: Record<string, mongoose.Model>, -- mongoose schemas to be converted and added into the specification
merge: Partial<OpenAPIV3_1.Document>, -- initial information to merge into the generated schema such as name, version, ...
options: {
generateTags: boolean, -- if OpenAPI tags should be generated per route group
reformatTemplates: boolean, -- if express templates in the format :parameter should be converted to the OpenAPI {paramter}
defaultResponse: boolean -- if a default response should be added incase none are specified by the user
}
)
SpecificationGenerator.generate() : OpenAPIV3_1.Document -- generate the full specification