Create an OpenAPI Specification

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

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:

Create a simple Node.js server
Create an OpenAPI Specification that models an API that calls the Node.js server

What you'll need

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

Apigee Edge account (see Create an Apigee Edge account)
Recent version of Node.js
curl command line tool
Text editor

Create a simple Node.js server

To create a simple Node.js server:

Create a file called index.js.

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!');
});

Save the file.
Install the required Express module:
```
npm install express
```
Start the server:
```
node index.js
```
The following message is returned:
Example app listening on port 3000
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.

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

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

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.
Click Save.
You are prompted to name the specification.
Enter a name for the specification, such as: simple-spec.
Click Continue.
The specification is saved.
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 API proxy from an OpenAPI Specification.