dapperdox
dapperdox copied to clipboard
It would be nice if parameters under "explore this API" are prefilled with the defaults
If the parameters are already prefilled with the default value from the spec. it would make it easier for the reader of the documentation to test the API and see what it does.
Minimal example:
{
"x-navigateMethodsByName": true,
"info": {
"title": "minimal"
},
"swagger": "2.0",
"host": "localhost:3123",
"paths": {
"/account": {
"get": {
"parameters": [ {
"name": "something",
"in": "query",
"description": "A parameter",
"type": "string",
"default": "a default"
} ],
"summary": "list",
"responses": {
"200": {
"description": "Success",
"schema": {
"title": "response",
"type": "string"
}
}
}
}
}
}
}
Will this not be, on the other hand, confusing? The default
value is the value the server will assume if the parameter is not provided in the API request. By pre-populating, we may be suggesting to the reader that the default is the value to send in the absence of another value.
swagger-ui pre-populates the fields with the default
value and this feature is very convenient for quickly showing how the API works. But yes, you are correct, using default
is not correct. Perhaps pre-populating the fields using a x-example
would be better just like http://dredd.readthedocs.io/en/latest/how-it-works/#uri-parameters uses?