OpenAPI specification provides a way to define the reusable components.
For example,
Step 1: Create a component that represent employee information.
components:
schemas:
employee:
type: object
properties:
id:
type: integer
example: 123
firstName:
type: string
example: krishna
lastName:
type: string
example: gurram
Step 2: Refer the definition of employee component in the document.
$ref: '#/components/schemas/employee'
Note:
After typing $ref: enter CTRL + SPACE to get the auto complete help.
data.yaml
openapi: 3.0.0
info:
title: Customer Data Aceess API
description: API to expose all the CRUD operations on customers
contact:
name: Krishna
email: krishna123@abc.com
url: https://self-learning-java-tutorial.blogspot.com/
version: 1.0.0
paths:
/employees/{employeeId}:
get:
parameters:
- in: path
name: employeeId
required: true
schema:
type: integer
example: 123
responses:
200:
description: Get Specific Employee Details
content:
application/json:
schema:
$ref: '#/components/schemas/employee'
/employees:
post:
description: Add new employee to the organization
requestBody:
content:
application/json:
schema:
type: object
properties:
firstName:
type: string
example: krishna
lastName:
type: string
example: gurram
responses:
201:
description: New Employee is created
content:
application/json:
schema:
$ref: '#/components/schemas/employee'
get:
parameters:
- in: query
name: from
description: Page number to return
required: true
schema:
type: integer
example: 1
- in: query
name: size
description: Number of elements to return
required: false
schema:
type: integer
example: 10
minimum: 10
maximum: 100
- in: header
name: onetime_token
description: token to be used at the time of login
required: false
schema:
type: string
example: 08c3372a-9314-49d6-b9dd-ff212c1715a5
responses:
200:
description: List of all the employees in organization
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/employee'
components:
schemas:
employee:
type: object
properties:
id:
type: integer
example: 1234
firstName:
type: string
example: krishna
lastName:
type: string
example: gurram
Add the content of data.yaml to swagger editor, you can see the API definitions at right side of window.
No comments:
Post a Comment