OpenAPI provides the definition standard of REST API for documentation.
This is useful for all service providers of REST API.
There are two formats of OpenAPI definition standard,yaml and json.
For example,we create the OpenAPI definition of REST API,using a following post.
To generate the OpenAPI definition from the server side code,we can use ChartGPT4.
The ChatGPT prompt sentence is “Output the OpenAPI definition of the following REST API in both YAML and JSON formats.”.
The result are followings.
- YAML
openapi: 3.0.0
info:
title: Sample Flask REST API
version: 1.0.0
paths:
/token:
post:
summary: Acquire JWT token
security:
- basicAuth: []
responses:
'200':
description: JWT token provided
content:
application/json:
schema:
type: object
properties:
access_token:
type: string
'500':
description: Bad request
/restapi/{id}:
post:
summary: Create data
security:
- jwtAuth: []
requestBody:
content:
application/json:
schema:
type: object
responses:
'200':
description: Data created
get:
summary: Retrieve data
parameters:
- in: path
name: id
required: true
schema:
type: string
responses:
'200':
description: Data retrieved
'500':
description: Bad ID
put:
summary: Update data
security:
- jwtAuth: []
parameters:
- in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
responses:
'200':
description: Data updated
'500':
description: Bad ID
delete:
summary: Delete data
security:
- jwtAuth: []
parameters:
- in: path
name: id
required: true
schema:
type: string
responses:
'200':
description: Data deleted
'500':
description: Bad ID
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
jwtAuth:
type: http
scheme: bearer
bearerFormat: JWT
- JSON
{
"openapi": "3.0.0",
"info": {
"title": "Sample Flask REST API",
"version": "1.0.0"
},
"paths": {
"/token": {
"post": {
"summary": "Acquire JWT token",
"security": [
{
"basicAuth": []
}
],
"responses": {
"200": {
"description": "JWT token provided",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"access_token": {
"type": "string"
}
}
}
}
}
},
"500": {
"description": "Bad request"
}
}
}
},
"/restapi/{id}": {
"post": {
"summary": "Create data",
"security": [
{
"jwtAuth": []
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Data created"
}
}
},
"get": {
"summary": "Retrieve data",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Data retrieved"
},
"500": {
"description": "Bad ID"
}
}
},
"put": {
"summary": "Update data",
"security": [
{
"jwtAuth": []
}
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Data updated"
},
"500": {
"description": "Bad ID"
}
}
},
"delete": {
"summary": "Delete data",
"security": [
{
We can show the API references as documents to import the definition by tools.
For example , APIDOC can show like below:
Also we can generate client side code to call a REST API.
Best Regards,
Comments