Writing comprehensive and accurate API specifications can be a time-consuming task. But with the power of ChatGPT, we’ve made the process much more easier! With the right prompt and a plugin, let’s see how you can produce an OpenAPI spec in record time.
Step 1: Gathering API Documentation
To begin, as a technical writer, you'll receive a set of links to API documentation from the developer. The links should be copied and pasted into the prompt below, allowing ChatGPT to analyze and extract the necessary information.
Step 2: Utilizing the Linkreader Plugin
The Linkreader plugin, a powerful tool, enables ChatGPT to read and comprehend the content of web pages. By utilizing this plugin, you can easily extract endpoints from each webpage in the API documentation. Alternatively, if the content is not available online or the Linkreader plugin is not accessible, you can manually copy and paste the content into the prompt.
Step 3: Applying API Spec Principles with the prompt
To ensure high-quality API specifications, it's important to adhere to specific principles during the writing process. Let's go through each principle and explore how to implement them effectively:
- Operation ID: Each endpoint in the API spec should have a unique operation ID, which helps to identify and reference it accurately.
- Parameter Description: Adding descriptions to the parameters used in the API endpoints enhances clarity and understanding for developers who consume the API.
- Summary for OpenAPI Paths: Including a summary for each OpenAPI path provides a concise overview of the endpoint's purpose and functionality.
- Grammar and Punctuation: Maintaining correct grammar and punctuation in descriptions and summaries contributes to the overall professionalism of the API documentation.
- Model Description: Describing the models used in the API spec helps developers comprehend the structure and attributes of the data exchanged through the API.
- Limited Endpoints: It's recommended to limit the number of endpoints per API spec to maintain clarity and ease of understanding.
- Response Examples: Providing examples for different response scenarios helps developers grasp the expected data formats and values.
- Informative Error Messages: It's crucial to guide users of the API, especially when they encounter errors like "not found" or incorrect requests. Clear error messages should be included, along with suggestions on the available endpoints and proper usage.
Step 4: Check the Produced API Specification
On a tool like this one: https://apitools.dev/swagger-parser/online/, check the OpenAPI specification produced by ChatGPT.
Voila: Generating API Specs
Once the principles mentioned above have been taken into account, ChatGPT can generate OpenAPI specs (version 3.0) based on the provided API documentation. The resulting API specs will consist of well-defined endpoints, parameter descriptions, summaries, model details, limited endpoints per spec, response examples, and informative error messages.
The prompt
"You are a technical writer and I am sending to you links to API documentation. I would like that you create API openAPI specs 3.0 for the link I share with you below:
***Insert API Documentation URL***
You need specifically to take into account the following principles when you write the API specs. Please, include all endpoints shared.
- You need to have operation id defined.
- Add description to parameters
- Add summary to open api paths
- Use correct grammar and ends the plugin description with punctuation
- Add description to the models
- Limited number of endpoints per API specs
- Examples should be provided for responses
- Provides informative error messages. Guide a user of the plugin about what they can do and the available endpoint for the API otherwise so they are not blocked. This is especially true for errors of not found or request that are not reflecting how the API is being used.”
Stop wasting your Ad budget
.jpg)
.jpg)
