
Security News
PyPI Now Supports iOS and Android Wheels for Mobile Python Development
PyPI now supports iOS and Android wheels, making it easier for Python developers to distribute mobile packages.
express-oas-generator
Advanced tools
Module to automatically generate OpenAPI (Swagger) specification for existing ExpressJS 4.x REST API applications
Module to:
Note - make sure to also read the Advanced usage (recommended) section after this!
npm i express-oas-generator --save
;const express = require('express');
const expressOasGenerator = require('express-oas-generator');
let app = express();
expressOasGenerator.init(app, {}); // to overwrite generated specification's values use second argument.
Second argument of expressOasGenerator.init(app, {})
could be either an object or a function. In case of the object generated spec will be merged with the object. In case of function it will be used to apply changes for generated spec. Example of function usage:
generator.init(app, function(spec) {
_.set(spec, 'info.title', 'New Title');
_.set(spec, 'paths[\'/path\'].get.parameters[0].example', 2);
return spec;
});
To write specification into a file use third and forth (optional) arguments. Full signature of init()
function is following:
expressOasGenerator.init(
app,
function(spec) { return spec; },
'path/to/a/file/filename.json',
60 * 1000,
'api-docs',
['User', 'Student'],
['users', 'students'],
['production'],
true,
SPEC_OUTPUT_FILE_BEHAVIOR.RECREATE
)
where the last parameters are:
SPEC_OUTPUT_FILE_BEHAVIOR.RECREATE
- (Optional) Enum to indicate if the spec outfile file is recreated or preserved from current content (SPEC_OUTPUT_FILE_BEHAVIOR.PRESERVE
)Instead of using a single init
handler, we'll use 2 separate ones - one for responses, and one for requests.
let app = express();
/** place handleResponses as the very first middleware */
expressOasGenerator.handleResponses(app, {});
/** initialize your `app` and routes */
/** place handleRequests as the very last middleware */
expressOasGenerator.handleRequests();
app.listen(PORT);
mind the order of the middleware handlers - first we apply the one for responses, then we apply the one for requests, which might seem counter-intuitive since requests come before responses, but this is how we need to do it because:
response.write()/end()
methods should be wrapped before any route or middleware call itbody-parser
Don't worry - we'll throw a loud error if you messed this up so that you can correct yourself quickly! 💥
See server_advanced.js for usage example.
In order to generate documentation, we need to analyze both responses and requests.
The tricky thing is - one handler must be placed as the very first middleware of the express app, and the other must be the very last. It is needed to intercept all the data (headers and payload) coming in and out out the app.
In the expressOasGenerator.init()
method, we assume that you place it straight after initializing the express app.
Inside we place response intercept middleware and then we call setTimeout
with 1000
miliseconds to make sure we place our request intercept middleware as the very last one.
The basic approach is error-prone because:
1000
milisecond setTimeout
passes and applies the request middleware.This could occur, for example, if you start your express server and then run the API tests immidiately - that wouldn't work. You'd have to start your server and then make your tests wait a second before the request middleware is applied.
If your service is running not at the root of the server add full base path URL to package.json
{
"baseUrlPath" : "/tokens"
}
Here is a sample
{
"name": "cwt-sts-svc",
"version": "1.1.48",
"description": "JWT generation service",
"keywords": [],
"author": "",
"main": "lib",
"baseUrlPath" : "/tokens",
"bin": {
"cwt-sts-svc": "bin/server"
}
}
This library uses swagger-ui-express as dependency , so if you need to edit the swagger's default documentation page style you can set swaggerDocumentOptions
. This option receives any custom swagger options and pass through when swaggerUi are configured.
You can follow these links to see how settings can be edited:
An basic example is:
generator.handleResponses(app, {
swaggerDocumentOptions: { customCss: '.swagger-ui { background-color: red }' }
});
And that would result in this:
Goal of the module is to provide developers with Swagger UI in development environments. Module process every request and response therefore it may slow down your app - is not supposed to be used in production environment.
Assuming you have ExpressJS REST API application and you
******
X-
treated as a apiKey type headers;Parameters and response body not documented!
Express-oas-generator (EOG) adds parameters handler as a very last middleware. If any middleware or path in router breaks the chain and doesn't pass execution to next middleware/router then very last EOG middleware won't be called. So call next() or next(err) as the very last line in your handler. Some docs:
For more info please read the entire issue report
Please read:
FAQs
Module to automatically generate OpenAPI (Swagger) specification for existing ExpressJS 4.x REST API applications
The npm package express-oas-generator receives a total of 0 weekly downloads. As such, express-oas-generator popularity was classified as not popular.
We found that express-oas-generator demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI now supports iOS and Android wheels, making it easier for Python developers to distribute mobile packages.
Security News
Create React App is officially deprecated due to React 19 issues and lack of maintenance—developers should switch to Vite or other modern alternatives.
Security News
Oracle seeks to dismiss fraud claims in the JavaScript trademark dispute, delaying the case and avoiding questions about its right to the name.