Create an OpenAPI Specification

In this tutorial, you create an OpenAPI Specification to model an API that calls a target server. The target server consists of a very simple Node.js-based server that you create and run on your machine. This tutorial takes about 10 minutes to complete.

What you'll learn

In this tutorial, you'll learn how to:

What you'll need

Here's what you'll need to get started:

Create a simple Node.js server

To create a simple Node.js server:

  1. Create a file called index.js.
  2. Copy the following Node.js code into the file:

    var express = require('express');
    var app = express();  
    
    app.get('/v1/hello', function (req, res) {
      res.setHeader("Access-Control-Allow-Origin", "*");
      res.send('Hello World!\n');
    });  
    
    app.listen(3000, function () {
      console.log('Example app listening on port 3000!');
    });
    
  3. Save the file.

  4. Install the required Express module:

    npm install express
    
  5. Start the server:

    $node index.js
    Example app listening on port 3000!
    

    The server is running on port 3000.

  6. Test the API by sending the following HTTP request.

    curl localhost:3000/v1/hello
    

    The API returns: Hello World!

Create an OpenAPI Specification

To create an OpenAPI Specification that models the API that calls the Node.js server.

  1. Sign in to apigee.com/edge.
  2. Select Develop > Specs in the side navigation bar.
    The list of specifications is displayed.
  3. Click + Spec and select New Spec in the drop-down menu.

  4. Copy the following YAML content:

    swagger: "2.0"
    info:
      version: "0.0.1"
      title: Hello World API
    host: 127.0.0.1:3000
    basePath: /v1
    schemes:
      - http
      - https
    consumes:
     - application/json
    produces:
      - application/json
    paths:
      '/hello':
        get:
          description: Returns greetings to the caller
          operationId: hello
          responses:
            "200":
              description: Success
              schema:
                $ref: "#/definitions/HelloWorldResponse"
            default:
              description: Error
              schema:
                $ref: "#/definitions/ErrorResponse"
    definitions:
      HelloWorldResponse:
        required:
          - message
        properties:
          message:
            type: string
          age:
            type: number
      ErrorResponse:
        required:
          - message
        properties:
          message:
            type: string
    
    
  5. Paste the YAML content into the left pane of the editor (overwriting the current content).

    Note: You can right-click in the left pane of the editor and select Select All to highlight the current contents, then right-click again and select Paste. Documentation for the specification is shown in the right pane.

  6. Click Save.
    You are prompted to name the specification.

  7. Enter a name for the specification, such as: simple-spec.

  8. Click Continue.
    The specification is saved.

  9. Click Close to close the specification and navigate back to the specification list.

The new specification is displayed in the specification list.

What's Next?

Congratulations! You have created your first OpenAPI Specification to model an API that calls a target server.

Next, learn how to create an Edge API proxy from an OpenAPI Specification.