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. 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.

Swagger editor tutorial