OpenAPI is a prevalent standard for defining and documenting APIs. Although generating documentation according to the OpenAPI specifications can be time-consuming, imagine the possibilities if this process were more streamlined. This is where ChatGPT comes into play, offering a transformative approach to creating OpenAPI specifications.
ChatGPT, with its natural language processing capabilities, offers a unique solution to the often complex and time-consuming task of writing OpenAPI specifications.
With ChatGPT, you can describe your API’s functionality in plain language, and the tool will help translate this into a structured OpenAPI spec.
Prompt:
Please generate an OpenAPI YAML definition incorporating the following details.
Ensure the inclusion of separate schemas for any nested objects.
Also, include request and response examples using the sample values provided.
API base URL - https://test.search.com/rest
Path - /search/v2
Method - POST
Query Parameter - testparam
Add service-level bearer token authentication for this endpoint
Sample Request Body
{
"q": "test",
"context": {
"country": "US",
"locale": "en",
"environment": "stage"
}
}
Sample Response
{
"totalCount": 1,
"result": [
{
"uri": "https://test.com/test.pdf",
"test1": [
[
"test1"
]
],
"test2": [
[
"test2"
]
],
"test3": "test3",
"test4": [
[
"test4_1",
"test4_2"
]
]
}
]
}Additional Prompts:
Include an enum named 'environment' with values 'stage', 'uat', and 'prod'. Give me the complete specification
Add a description for the request body field 'q', labeling it as 'Product Code. Give me the complete specificationThis process will develop the OpenAPI specification based on the provided API details. The prompts can be further refined for a more precise API specification. Additionally, incorporating extra prompts will allow for even more detailed fine-tuning of the specification.
openapi: 3.0.0
info:
title: Test Search API
version: 1.0.0
servers:
- url: https://test.search.com/rest
paths:
/search/v2:
post:
summary: Search endpoint
operationId: search
parameters:
- name: testparam
in: query
required: false
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SearchRequest'
examples:
example1:
value:
q: "test"
context:
country: "US"
locale: "en"
environment: "stage"
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
examples:
example1:
value:
totalCount: 1
result:
- uri: "https://test.com/test.pdf"
test1: [["test1"]]
test2: [["test2"]]
test3: "test3"
test4: [["test4_1", "test4_2"]]
security:
- bearerAuth: []
components:
schemas:
SearchRequest:
type: object
properties:
q:
type: string
description: Product Code
context:
$ref: '#/components/schemas/Context'
Context:
type: object
properties:
country:
type: string
locale:
type: string
environment:
type: string
enum: [stage, uat, prod]
SearchResponse:
type: object
properties:
totalCount:
type: integer
result:
type: array
items:
$ref: '#/components/schemas/ResultItem'
ResultItem:
type: object
properties:
uri:
type: string
format: uri
test1:
type: array
items:
type: array
items:
type: string
test2:
type: array
items:
type: array
items:
type: string
test3:
type: string
test4:
type: array
items:
type: array
items:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWTNow, you can import the YAML specification to Swagger Editor so that you can review the API details and test the API through the browser. Refer to https://github.com/swagger-api/swagger-editor for more information on Swagger Editor on your local machine.
Now you can either upload the YAML file generated or directly paste the YAML file on the Editor.
You can review the various API details through the UI and test the API by providing the required authorization and the request payloads.
You can even host a local server to share the API specifications with teams.
Another option is the online Swagger Hub, a licensed version, but the free trial is available for testing; here, you can upload the API specification, review, test, and share it with the teams.
Import the definition
Now, you can review, test, and share the API with the teams.
Also, another option to share the API is through Confluence; the Swagger UI can be integrated into Confluence through the Swagger Plugin, and the UI can be embedded into the Confluence page and shared with different teams.
Enable one of the Open API Integration plugins from the confluence marketplace, I am going to use “Open API Documentation for Confluence” that supports both JSON and YAML (you can use the free trial version to test)
Now add the plugin inside the Confluence document.
You can embed the OpenAPI YAML or JSON specification from remote systems or directly paste it into the plugin.
Now the Swagger UI is embedded into the confluence page, the API can be reviewed and tested and the confluence page can be shared with different teams.
The API documentation is critical; the OpenAPI specification allows you to document the API details in a standard way. ChatGPT helps you to simplify the documentation process; you can use ChatGPT to create the basic documentation and modify it based on your need also follow the option to share with the different teams.
