You first start with a swagger key and its value is always 2.00 in quotes.
This is because before it became the Open API Specification, the specification was called Swagger 2.0
Request
Request will have the URL end point, the HTTP method, path parameters, query parameters, request body, responses.
paths
First there is paths key which will have a list of paths.
In other words different operations grouped by URL.
YAML has a dash which inidicates a list. That's because we have a list of parameters.
The query parameter has a name key which in this case has a start value and it has an in key which has a value of query, which means that it's a query parameter.
The required key is set to false in this case, indicating that the start parameter is optional, and the type key is set to the string.
This URL ends in /album/integer where the integer is the album ID.
So if we look at the definition in the paths key is now /album/ID where ID is in curly brackets.
This indicates that there will be a path parameter defined later with a name of ID.
Again we have a method of get in the parameters list. This time we have just one parameter, which, as I mentioned before, has a name of id.
The in value is path, which means that it's a path parameter and that's part of URL.
In this case, required is true and that's almost always the case for path parameters. And the type is integer.
the type key can have serveral values.
These include:
boolean, which can be true or false;
integer, which is a whole number; number; which can be either whole or decimal;
string, which is text;
array, which is a list of items.
Custom headers
If your request has custom headers, they are also treated as parameters.
In this example, you have this YAML code in the parameters list for a header named Access-level.
The in value is set to header, meaning that it's the header; the required value is false, meaning that it's optional; and the type is string.
Swagger Editor
The Swagger web site provides an editor for Open API Specification files. Go to editor2.swagger.io
It creates color-coded YAML on the left side on the right side it shows you what the documentation will look like once you create it.
Start
You first start with a swagger key and its value is always 2.00 in quotes.
This is because before it became the Open API Specification, the specification was called Swagger 2.0
Request
Request will have the URL end point, the HTTP method, path parameters, query parameters, request body, responses.
paths
First there is paths key which will have a list of paths.
In other words different operations grouped by URL.
YAML has a dash which inidicates a list. That's because we have a list of parameters.
The query parameter has a
namekey which in this case has a start value and it has aninkey which has a value of query, which means that it's a query parameter.The required key is set to false in this case, indicating that the start parameter is optional, and the type key is set to the string.
This URL ends in /album/integer where the integer is the album ID.
So if we look at the definition in the paths key is now /album/ID where ID is in curly brackets.
This indicates that there will be a path parameter defined later with a name of ID.
Again we have a method of
getin the parameters list. This time we have just one parameter, which, as I mentioned before, has a name of id.The
invalue is path, which means that it's a path parameter and that's part of URL.In this case, required is true and that's almost always the case for path parameters. And the type is integer.
the type key can have serveral values.
These include:
Custom headers
If your request has custom headers, they are also treated as parameters.
In this example, you have this YAML code in the parameters list for a header named Access-level.
The
invalue is set to header, meaning that it's the header; the required value is false, meaning that it's optional; and the type is string.Swagger Editor
The Swagger web site provides an editor for Open API Specification files. Go to
editor2.swagger.ioIt creates color-coded YAML on the left side on the right side it shows you what the documentation will look like once you create it.