Specifying API Specs

How to specify API specifications using generative AI

APIs (application programming interfaces) are applications that orchestrate calls and responses between systems.

Consider an instant message on an application like WhatsApp. When the user sends a message, it is going to an url (endpoint) that might be something like https://apis.whatsapp.com/messenger/thread/{threadId}. The message is received by this API and then written into a database.

Creating an OpenAPI specification for your bicycle rental application API middleware is a great way to establish clear documentation and generate boilerplate code for your Node.js Express server. In this article, we will walk through the process of creating an OpenAPI specification and then generating a Node.js Express application based on that specification.

Step 1: Design the OpenAPI Specification

Start by designing the OpenAPI specification for your bicycle rental application. The specification should define the API's endpoints, request and response formats, and any necessary authentication or authorization details. Here's a simple example of an OpenAPI specification for a bicycle rental application:

chatgpt-4

create an openapi spec for a bicycle rental api

openapi: 3.0.0
info:
  title: Bicycle Rental API
  version: 1.0.0

paths:
  /bicycles:
    get:
      summary: Get a list of available bicycles
      responses:
        '200':
          description: Successfully retrieved the list of bicycles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Bicycle'
  /bicycles/{bicycleId}:
    get:
      summary: Get the details of a specific bicycle
      parameters:
        - name: bicycleId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved the bicycle details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bicycle'

components:
  schemas:
    Bicycle:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
        pricePerHour:
          type: number

Save the specification in a file named bicycle-rental-api.yaml.

Below I have imported the spec into the documentation to demonstrate that the created spec compiles successfully.

Note the above is a very simple API specification. You could use prompt patterns from the replacement, transformation, and generation knowledges areas to build out a production grade API spec.

Get a list of available bicycles

GET/bicycles

Response

200

Successfully retrieved the list of bicycles

Body

application/json

idstring

namestring

typestring

pricePerHournumber

Request

JavaScriptCurlPython

const response = await fetch('/bicycles', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

[
  {
    "id": "text",
    "name": "text",
    "type": "text",
    "pricePerHour": 0
  }
]

Get the details of a specific bicycle

GET/bicycles/{bicycleId}

Path parameters

bicycleId*string

Response

200

Successfully retrieved the bicycle details

Body

application/json

idstring

namestring

typestring

pricePerHournumber

Request

JavaScriptCurlPython

const response = await fetch('/bicycles/{bicycleId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "id": "text",
  "name": "text",
  "type": "text",
  "pricePerHour": 0
}

Step 2: Generate the Node.js Express Code

To generate the Node.js Express code based on your OpenAPI specification, you can use tools like OpenAPI Generator or swagger-node-codegen. In this example, we'll use the OpenAPI Generator.

First, install the OpenAPI Generator CLI:

npm install -g @openapitools/openapi-generator-cli

Next, generate the Node.js Express code:

openapi-generator generate -i bicycle-rental-api.yaml -g nodejs-express-server -o ./bicycle-rental-api

This command will create a new directory named bicycle-rental-api, containing the generated Node.js Express code based on your OpenAPI specification.

Step 3: Set Up and Run the Generated Express Server

Navigate to the bicycle-rental-api directory and install the required dependencies:

cd bicycle-rental-api
npm install

Now, run the generated Express server:

npm start

Your Express server should now be running, and you can access the API endpoints as defined in your OpenAPI specification.

Conclusion

By creating an OpenAPI specification for your bicycle rental application API middleware and using a code generation tool, you can establish clear documentation and kickstart your Node.js Express server development. As you continue to develop your application, you can update the OpenAPI specification to reflect changes or additions to your API and regenerate the server code as needed.