Swagger

What is swagger
 Swagger is a open source API documentation framework that helps developers in design,
document, and consume RESTful web services
 Swagger reads an API and extract in the form of interactive UI called as Swagger UI
 Swagger UI offers HTML view of API with JSON support so that we can directly test our API
 It is one of most popular tools for generating interactive documentation from API

Postman vs. Swagger

 In postman each and every CRUD method must be selected and populated manually
 If there any change In REST API, every change must be manually changed in POSTman
 Swagger automatically capture the details from API, it reads various methods exposed through
API and presenting it in readable and compact screen
 If there is any change in the REST API it automatically read the updated code and update the
Swagger UI just by restarting the app
 Apart from that in Swagger we do not need to do any other setup in request header and body to
test the REST api method, just by click it bring whole json details which is needed.

Real time swagger use case

 It is good in cases when there are a lot of methods that are depending from each other and for
testing those methods
 Also anybody who wants to consumes the REST API’s may use swagger as a documentation by
looking at swagger UI

Important facts about swagger

 It is most widely adopted API documentation framework and it is especially standardized for
REST API services
 Huge community for support
 It drastically reduce the understanding curve for an API with various automation features

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which
allows both humans and computers to discover and understand the capabilities of the service without
access to source code, documentation, or through network traffic inspection. When properly defined, a
consumer can understand and interact with the remote service with a minimal amount of
implementation logic.

An OpenAPI definition can then be used by documentation generation tools to display the API, code
generation tools to generate servers and clients in various programming languages, testing tools, and
many other use cases.
Swagger Hub: SwaggerHub brings together all of the open source Swagger tooling into one easy-to-use
platform in the cloud. With SwaggerHub, you don’t need to download any additional tools to design,
document, or build your API, although we do offer integrations to other platforms to sync and deploy
your API. SwaggerHub also allows you to save and backup your API in the cloud.

Responses:

Describing Responses
An API specification needs to specify the responses for all API operations. Each operation
must have at least one response defined, usually a successful response. A response is
defined by its HTTP status code and the data returned in the response body and/or
headers. Here is a minimal example:

Response Media Types

An API can respond with various media types. JSON is the most common format for data
exchange, but not the only one possible. To specify the response media types, use
the content keyword at the operation level.
HTTP Status Codes
Under responses, each response definition starts with a status code, such as 200 or 404.
An operation typically returns one successful status code and one or more error statuses.
To define a range of response codes, you may use the following range definitions: 1XX, 2XX,
3XX, 4XX, and 5XX. If a response range is defined using an explicit code, the explicit code
definition takes precedence over the range definition for that code. Each response status
requires a description. For example, you can describe the conditions for error responses.
Markdown (CommonMark) can be used for rich text representation.

Note that an API specification does not necessarily need to cover all possible HTTP response
codes, since they may not be known in advance. However, it is expected to cover successful
responses and any known errors. By “known errors” we mean, for example, a 404 Not
Found response for an operation that returns a resource by ID, or a 400 Bad Request
response in case of invalid operation parameters.

Response Body
The schema keyword is used to describe the response body. A schema can define:

 an object or an array — typically used with JSON and XML APIs,

 a primitive data type such as a number or string – used for plain text
responses,
 a file – (see below).

Schema can be defined inline in the operation:

or defined in the global components.schemas section and referenced via $ref. This is

useful if multiple media types use the same schema.