doc-catcher
v4.1.4
Published
An express middleware that generates OpenAPI documentation by parsing successful API calls.
Downloads
36
Readme
Setup
After installing the package, create a new file api_spec_config.json
in the folder that contains your package.json file. The contents of the new file should be as follows:
{
"specfile":"./src/constants/APISpec.json",
"updateSpecs":true
}
specfile
specifies the location of the file in which the updated documentation is to be written.
updateSpecs
specifies if the documentation is to be updated on new API calls.
Local Specification
Use the exported middleware APIDocMiddleware
before the controllers whose transactions you wish to capture for documentation.
@JsonController('/route')
@UseBefore(APIDocMiddleware)
export class MyRoutesController{
...
}
Global Specification
Specify middlewares: [APIDocMiddleware]
in createExpressServer
Swagger Integration
And here's the setup in the app.ts file:
import swaggerUi from 'swagger-ui-express';
import { readFileSync } from "fs";
import { APIDocMiddleware } from "doc-catcher";
const app: express.Application = createExpressServer({
cors: {
origin: ...,
methods: "GET,POST,PUT,PATCH,DELETE",
credentials: true
},
controllers: [__dirname + "/controllers/**"],
/*
just for global integration:
middlewares: [APIDocMiddleware]
*/
});
if (nodeEnvironment !== "production") {
app.use('/docs', swaggerUi.serve, swaggerUi.setup(
JSON.parse(
readFileSync(
APIDocMiddleware.specPath,
{ encoding: 'utf-8', flag: 'r' }
)
)
))
}
export default app;
Testing and Setup
The contents of the APISpec.json
when it's created
{
"openapi": "3.0.1",
"info": {
"version": "1.0.0",
"title": "REST API for 'the repository to replace all repositories'",
"description": "This is the REST API for my repository. It isn't entirely useless."
},
"servers": [],
"tags": [],
"paths": {}
}