# Specifying API Specs 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: {% 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. {% hint style="info" %} Note the above is a very simple API specification. You could use prompt patterns from the [replacement](/gdf-full-stack-engineering/subject-knowledge-areas/replacement.md), [transformation](/gdf-full-stack-engineering/subject-knowledge-areas/transformation.md), and [generation ](/gdf-full-stack-engineering/subject-knowledge-areas/generation.md)knowledges areas to build out a production grade API spec. {% endhint %} {% openapi src="/files/0nDRreHJmeHLXOLLkjIX" 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="/files/0nDRreHJmeHLXOLLkjIX" 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.gdf.ai/gdf-full-stack-engineering/subject-knowledge-areas/specification/specifying-api-specs.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.