dereference + async

README.md

@@ -40,7 +40,7 @@ const options = {
   apis: ['./src/routes*.js'], // files containing annotations as above
 };
 
-const openapiSpecification = swaggerJsdoc(options);
+const openapiSpecification = await swaggerJsdoc(options);
 ```
 
 The resulting `openapiSpecification` will be a [swagger tools](https://swagger.io/tools/)-compatible (and validated) specification.
@@ -70,6 +70,22 @@ yarn add swagger-jsdoc
 - OpenAPI 3.x
 - Swagger 2
 
+## $ref dereference
+
+If you want to dereference all refs in specification set `dereference` flag in options.
+
+```javascript
+const options = {
+  dereference: true,
+};
+```
+
+## Breaking changes
+
+## 7.x
+
+- Result of `swaggerJsdoc()` is async
+
 ## Documentation
 
 Click on the version you are using for further details:

bin/swagger-jsdoc.js

@@ -71,16 +71,16 @@ if (!program.args.length) {
 
 const format = path.extname(output);
 
-const result = swaggerJsdoc({
+swaggerJsdoc({
   swaggerDefinition,
   apis: program.args,
   format,
-});
-
-if (format === '.json') {
-  fs.writeFileSync(output, JSON.stringify(result, null, 2));
-} else {
-  fs.writeFileSync(output, result);
-}
+}).then((result) => {
+  if (format === '.json') {
+    fs.writeFileSync(output, JSON.stringify(result, null, 2));
+  } else {
+    fs.writeFileSync(output, result);
+  }
 
-console.log('Swagger specification is ready.');
+  console.log('Swagger specification is ready.');
+});

examples/app/app.js

@@ -43,12 +43,11 @@ const options = {
   apis: ['./examples/app/routes*.js', './examples/app/parameters.yaml'],
 };
 
-// Initialize swagger-jsdoc -> returns validated swagger spec in json format
-const swaggerSpec = swaggerJsdoc(options);
-
 // Serve swagger docs the way you like (Recommendation: swagger-tools)
-app.get('/api-docs.json', (req, res) => {
+app.get('/api-docs.json', async (req, res) => {
   res.setHeader('Content-Type', 'application/json');
+  // Initialize swagger-jsdoc -> returns validated swagger spec in json format
+  const swaggerSpec = await swaggerJsdoc(options);
   res.send(swaggerSpec);
 });
 

examples/extensions/extensions.spec.js

@@ -2,8 +2,8 @@ const swaggerJsdoc = require('../..');
 const referenceSpecification = require('./reference-specification.json');
 
 describe('Example for using extensions', () => {
-  it('should support x-webhooks', () => {
-    const result = swaggerJsdoc({
+  it('should support x-webhooks', async () => {
+    const result = await swaggerJsdoc({
       swaggerDefinition: {
         info: {
           title: 'Example with extensions',

examples/yaml-anchors-aliases/yaml-anchors-aliases.spec.js

@@ -2,8 +2,8 @@ const swaggerJsdoc = require('../..');
 const referenceSpecification = require('./reference-specification.json');
 
 describe('Example for using anchors and aliases in YAML documents', () => {
-  it('should handle references in a separate YAML file', () => {
-    const result = swaggerJsdoc({
+  it('should handle references in a separate YAML file', async () => {
+    const result = await swaggerJsdoc({
       swaggerDefinition: {
         info: {
           title: 'Example with anchors and aliases',