Swagger - Adding a Request

Let's define requests for getting a photo albums. The following is the information that will be included in the request:

  • URL endpoint
  • HTTP Method
  • Path parameters
  • Query parameters

Let's understand the query parameters through an example.

Get https://api.javahubpoint.com/photo/album?start=2021-05-01&end=2021-05-31

API Definition file

// Endpoints  
paths:  
 # photo album  
 /album  
# Get one or more albums  
get:  
   #Query parameters  
  parameters:  
   # Starting date  
     -name: start  
      in: query  
    required: false  
   type: string  
# Ending date  
   -name: end  
    in: query  
    required: false  
    type: string   

It starts with a 'paths' key which is the list of keys. In other words, we can say that list of operations by this url are grouped in the paths key. This key starts with '/album' which means that the url ends with '/album'. 

The method that returns one or more albums uses the GET method so we put after the '/album'. The get method has a list of parameters. In the above YAML, list begins with a '-' because API definition file has a list of query parameters. The list has keys:

  • name: It is the key that denotes the name of the parameter.
  • in: It is the key that defines the parameter as a query-based parameter.
  • required: In the above, the value of this key is false which means that it is an optional field.
  • Type: It is the key that defines the type of the parameter.


Now we retrieve the album of a specific id. Suppose the url of retrieving a specific album is given below:

Get https://api.javahubpoint.com/photo/album/12345

The above url will retrieve the specific url having unique id 12345. Let's look at the definition.

# photo album  
  /album/{id}:  
   # get an album  
   get:  
     # Query parameters  
     parameters:  
     # Album id  
    -name: id  
 in: path  
required: true  
type: integer   

In the above YAML, the key is defined as /album/{id} where id is defined within the curly brackets. This indicates that the path parameter will be defined later with a name 'id'. 

Then, we have a get method and then we included a parameter list. Here we have added only one list item named as 'id'. 

The 'in' value is path which means that it is a path parameter, the 'required' field is true which will always be the case in the path parameter, and the type is integer.