# Specifying API Specs

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

Consider an instant message on an application like <mark style="color:green;">WhatsApp</mark>. 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.&#x20;

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:

{% code title="chatgpt-4" overflow="wrap" %}

```
create an openapi spec for a bicycle rental api
```

{% endcode %}

{% code overflow="wrap" %}

```yaml
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
```

{% endcode %}

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.&#x20;

{% hint style="info" %}
Note the above is a very simple API specification. You could use prompt patterns from the [replacement](https://docs.gdf.ai/gdf-full-stack-engineering/subject-knowledge-areas/replacement), [transformation](https://docs.gdf.ai/gdf-full-stack-engineering/subject-knowledge-areas/transformation), and [generation ](https://docs.gdf.ai/gdf-full-stack-engineering/subject-knowledge-areas/generation)knowledges areas to build out a production grade API spec.&#x20;
{% endhint %}

{% openapi src="<https://2604738549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSITvwYTPqL7dizjFLHv4%2Fuploads%2FIK9FC85XumncKQXMsA76%2Fbicycle-api.yaml?alt=media&token=2c4207f6-5cf1-4d99-99ac-79f4a7ffce8a>" path="/bicycles" method="get" %}
[bicycle-api.yaml](https://2604738549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSITvwYTPqL7dizjFLHv4%2Fuploads%2FIK9FC85XumncKQXMsA76%2Fbicycle-api.yaml?alt=media\&token=2c4207f6-5cf1-4d99-99ac-79f4a7ffce8a)
{% endopenapi %}

{% openapi src="<https://2604738549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSITvwYTPqL7dizjFLHv4%2Fuploads%2FIK9FC85XumncKQXMsA76%2Fbicycle-api.yaml?alt=media&token=2c4207f6-5cf1-4d99-99ac-79f4a7ffce8a>" path="/bicycles/{bicycleId}" method="get" %}
[bicycle-api.yaml](https://2604738549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSITvwYTPqL7dizjFLHv4%2Fuploads%2FIK9FC85XumncKQXMsA76%2Fbicycle-api.yaml?alt=media\&token=2c4207f6-5cf1-4d99-99ac-79f4a7ffce8a)
{% endopenapi %}

### 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](https://github.com/OpenAPITools/openapi-generator) or [swagger-node-codegen](https://github.com/fmvilas/swagger-node-codegen). In this example, we'll use the OpenAPI Generator.

First, install the OpenAPI Generator CLI:

{% code overflow="wrap" %}

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

{% endcode %}

Next, generate the Node.js Express code:

{% code overflow="wrap" %}

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

{% endcode %}

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:

{% code overflow="wrap" %}

```bash
cd bicycle-rental-api
npm install
```

{% endcode %}

Now, run the generated Express server:

{% code overflow="wrap" %}

```bash
npm start
```

{% endcode %}

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.