Let's take a quick look at the Swagger file structure before moving further. The Swagger 1.x file contents that describe the RESTful APIs are represented as the JSON objects. With Swagger 2.0 release onwards, you can also use the YAML format to describe the RESTful web APIs.

This section discusses the Swagger file contents represented as JSON. The basic constructs that we'll discuss in this section for JSON are also applicable for the YAML representation of APIs, although the syntax differs.

When using the JSON structure for describing the REST APIs, the Swagger file uses a Swagger object as the root document object for describing the APIs. Here is a quick overview of the various properties that you will find in a Swagger object:

• The following properties describe the basic information about the RESTful web application:
  • swagger: This property specifies the Swagger version.
  • info: This property provides metadata about the API.
  • host: This property locates the server where the APIs are hosted.
  • basePath: This property is the base path for the API. It is relative to the value set for the host field.
  • schemes: This property transfers the protocol for a RESTful web API, such as HTTP and HTTPS.

• The following properties allow you to specify the default values at the application level, which can be optionally overridden for each operation:
  • consumes: This property specifies the default internet media types that the APIs consume. It can be overridden at the API level.
  • produces: This property specifies the default internet media types that the APIs produce. It can be overridden at the API level.
  • securityDefinitions: This property globally defines the security schemes for the document. These definitions can be referred to from the security schemes specified for each API.

• The following properties describe the operations (REST APIs):
  • paths: This property specifies the path to the API or the resources. The path must be appended to the basePath property in order to get the full URI.
  • definitions: This property specifies the input and output entity types for operations on REST resources (APIs).
  • parameters: This property specifies the parameter details for an operation.
  • responses: This property specifies the response type for an operation.
  • security: This property specifies the security schemes in order to execute this operation.
  • externalDocs: This property links to the external documentation.