Step 1: Create API definition file
employees.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: [email protected]
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'
application/xml:
schema:
$ref: '#/components/schemas/employee'
application/csv:
schema:
$ref: '#/components/schemas/employee'
403:
$ref: '#/components/responses/403Unauthorized'
500:
$ref: '#/components/responses/500InternalServerError'
/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'
403:
$ref: '#/components/responses/403Unauthorized'
500:
$ref: '#/components/responses/500InternalServerError'
get:
parameters:
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/pageNumber'
- 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'
403:
$ref: '#/components/responses/403Unauthorized'
500:
$ref: '#/components/responses/500InternalServerError'
components:
parameters:
pageSize:
in: query
name: size
description: Number of elements to return
required: false
schema:
type: integer
example: 10
minimum: 10
maximum: 100
pageNumber:
in: query
name: from
description: Page number to return
required: true
schema:
type: integer
example: 1
responses:
403Unauthorized:
description: User do not have permission to access this API
content:
application/json:
schema:
type: object
properties:
statusCode:
type: integer
example: 403
message:
type: string
example: Unauthorized
500InternalServerError:
description: Unable to process the request
content:
application/json:
schema:
type: object
properties:
statusCode:
type: integer
example: 500
message:
type: string
example: Internal Server Error
schemas:
employee:
type: object
required:
- firstName
- id
properties:
id:
type: integer
example: 1234
firstName:
type: string
example: krishna
lastName:
type: string
example: gurram
Step 2: Copy the dist folder from swagger UI installation directory to some other location.
Step 3: Rename the copied dist folder to MyFirstSwaggerApp.
Step 4: Copy employees.yaml file to ‘MyFirstSwaggerApp’ directory.
Step 5: Open index.html file from ‘MyFirstSwaggerApp’ in any text editor.
Update below statement with employees.yaml
url: "https://petstore.swagger.io/v2/swagger.json"
It is updated like below.
url: "employees.yaml"
Step 5: Navigate to the parent directory of ‘MyFirstSwaggerApp’ directory and execute below command.
http-server MyFirstSwaggerApp -a 127.0.0.1 -p 9090
$ls
MyFirstSwaggerApp swagger-editor-3.6.31 swagger-ui-3.23.3
$
$http-server MyFirstSwaggerApp -a 127.0.0.1 -p 9090
Starting up http-server, serving MyFirstSwaggerApp
Available on:
http://127.0.0.1:9090
Hit CTRL-C to stop the server Open the url ‘http://127.0.0.1:9090/index.html#/ ‘ in browser, you can see the interactive documentation provided by swagger UI.
Related Articles
This post first appeared on Java Tutorial : Blog To Learn Java Programming, please read the originial post: here
