swagger-api / swagger-api/swagger-parser

Validate method modifies the input 'api' param inplace

Open
#1,135 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Java
Stars
867
Forks
560
Avg merge
2d 21h
Merged PRs (30d)
7

Description

The following code alters the contents of inputAPIDoc:


var SwaggerParser = require('swagger-parser');
var inputAPIDoc = {
    "swagger": "2.0",
    "info": {
        "version": "0.0.0",
        "title": "Simple API"
    },
    "paths": {
        "/": {
            "get": {
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/ScoredTopic"
                        }
                    },
                    "400": {
                        "description": "bad request",
                        "schema": {
                            "$ref": "#/definitions/badreq"
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "ScoredTopic": {
            "properties": {
                "topics": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/ScoredTopic"
                    }
                }
            }
        },
        "badreq": {
            "properties": {
                "topics": {
                    "type": "string",
                    "description": "details on why the error occured"
                }
            }
        }
    }

}
console.log(JSON.stringify(inputAPIDoc));
SwaggerParser.validate(inputAPIDoc, { dereference: { circular: false } }, function (err, api) {
    console.log("--------------------------");
    console.log(JSON.stringify(inputAPIDoc));
    if (err) {
        if (err.name === "ReferenceError" && err.message === "The API contains circular references") {
            console.log(err.message);
        }
        else {
            console.log(err);
        }
    }
    else {
        console.log("success");
    }
});

setTimeout(function () {
    console.log("**************************");
    console.log(JSON.stringify(inputAPIDoc));
}, 2000);

Output of the above code:

{"swagger":"2.0","info":{"version":"0.0.0","title":"Simple API"},"paths":{"/":{"get":{"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/ScoredTopic"}},"400":{"description":"bad request","schema":{"$ref":"#/definitions/badreq"}}}}}},"definitions":{"ScoredTopic":{"properties":{"topics":{"type":"array","items":{"$ref":"#/definitions/ScoredTopic"}}}},"badreq":{"properties":{"topics":{"type":"string","description":"details on why the error occured"}}}}}
--------------------------
{"swagger":"2.0","info":{"version":"0.0.0","title":"Simple API"},"paths":{"/":{"get":{"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/ScoredTopic"}},"400":{"description":"bad request","schema":{"properties":{"topics":{"type":"string","description":"details on why the error occured"}}}}}}}},"definitions":{"ScoredTopic":{"properties":{"topics":{"type":"array","items":{"$ref":"#/definitions/ScoredTopic"}}}},"badreq":{"properties":{"topics":{"type":"string","description":"details on why the error occured"}}}}}
The API contains circular references
**************************
{"swagger":"2.0","info":{"version":"0.0.0","title":"Simple API"},"paths":{"/":{"get":{"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/ScoredTopic"}},"400":{"description":"bad request","schema":{"properties":{"topics":{"type":"string","description":"details on why the error occured"}}}}}}}},"definitions":{"ScoredTopic":{"properties":{"topics":{"type":"array","items":{"$ref":"#/definitions/ScoredTopic"}}}},"badreq":{"properties":{"topics":{"type":"string","description":"details on why the error occured"}}}}}

As we can see, the value of the var inputAPIDoc is altered on return from the validate call.
API documentation does not talk about this. Hence would be better if the same is clarified

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the SwaggerParser.validate API documentation and its handling of the input API object, as shown in the issue example. Document whether validation may modify the supplied object, including the observed dereferencing behavior, and ensure the documented behavior matches the implementation.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.