Note the inclusion of a parameter which is specified in the body of the request from the in:body description. This would be under the /artists resource. It is not advisable to use these parameters in GET and DELETE actions.įor this API, let’s add the ability for a user to post an artist to our database. Body parameters are great for POST and PUT requests. A key principle of such a parameter is that resources are sent in the message body.
Thus, the definition would now look as follows – swagger: '2.0'ĭescription: Limits the number of items on a pageĭescription: Specifies the page number of the artists to be displayedīody parameters are stated in the body of the request. These variables are defined under the parameters object in the Swagger definition. The client could describe the page number (offset) and the amount of information on the page (limit), for example: GET In our example, it would make sense to let the client limit the information required instead of returning the entire list of artists from the database, which would lead to unnecessary load on the server. It is a non-hierarchical component of the URL. Query parameters are optional and non unique, so they can be specified multiple times in the URL. They appear at the end of a URL following a question mark. Query parameters are the most common type of parameters. See here for more information on responses. # - Added lines -ĭescription: Successfully returned a list of artists An unsuccessful request is described under the 400 HTTP code, with a corresponding error message detailing why the response is invalid. A successful response will return the artist name, genre, username and albums recorded. You can find more information about HTTP status codes here. In our sample code, we have specified 200, which is a successful client request, while 400 is an unsuccessful request. The description gives details on what the responses of the API would be.
Swagger editor examples code#
The GET method, under the artists endpoint, lets the consumer of the API obtain the details of a list of artists from the database.Įvery response would need at least one HTTP status code to describe the kind of responses a consumer is likely to expect. Let’s start with a simple meta information section: swagger: '2.0'ĭescription: A simple API to understand the Swagger Specification in greater detail We can also add a basic authentication which only lets authorized users consume the API. In this case, it is, which is defined by the schemes, host and basePath objects respectively. The base URL is what any application or end user will call in order to consume the API. The info object is then specified with additional, required metadata like the version and title. Information like what the API does, what the base URL of the API is and what web-based protocol it follows can be defined in this section.Īll Swagger defined APIs start with the swagger: 2.0 declaration. The meta information section is where you can give information about your overall API. The syntax above will make sense once we finish this walkthrough. Swagger can be written in JSON or YAML, though we recommend writing it in YAML, because it is easier to read and understand.Ī simple Swagger definition looks like this: swagger: '2.0'ĭescription: An API to illustrate Swagger In this tutorial, we will write an API definition in the Swagger 2.0 format (also known as OpenAPI 2.0).
Fast forward 6 years and Swagger has become the de-facto standard for designing and describing RESTful APIs used by millions of developers and organizations for developing their APIs, be it internal or client facing. Swagger’s journey started in 2010 when it was developed by Reverb Technologies (formerly called Wordnik) to solve the need for keeping the API design and documentation in sync.
Swagger is an open-source framework for designing and describing APIs.
0 kommentar(er)
