Crafting an Apigee OpenAPI Spec

The OpenAPI specification not only describes your API in detail, it’s actually the blueprint from which the actual API proxy is initially constructed. Moreover, the OpenAPI specification is the source from which the SmartDocs documentation is generated. In this hands-on lab, we’ll start with a default Apigee specification and then go through the steps necessary to update it so it is truly a working spec, capable of calling a real-world API — and getting real-time results.

Learning Objectives

Successfully complete this lab by achieving the following learning objectives:

Create New Specification

From the Apigee dashboard, choose Specs.
Click the + Spec button and select New Spec.

Modify the Default Spec

In the spec editor, change swagger: '2.0' to openapi: "3.0.2".

Change info to the following:

version: "2.5"
title: OpenWeatherMap API

Remove the host and schemes sections.

Add the following section:

servers:
- url: https://api.openweathermap.org/data/2.5

After servers, add:
```
security:
- app_id: []
```

Change paths to the following:

paths:
# This is a path endpoint. Change it.
/weather:
# This is a HTTP operation
get:
  tags:
  - Current weather data
  # Describe this verb here. Note: you can use markdown
  description: "Gets `Weather` objects."
  # This is array of GET operation parameters
  operationId: CurrentWeatherData
  parameters:
  - name: q
    in: query
    description: "**City name**. *Example: brooklyn,us*."
    schema:
      type: string

  - name: zip
    in: query
    description: "**Zip code**. Search by zip code. *Example: 95050,us*."
    schema:
      type: string

  responses:
    200:
      description: Successful response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/200'
    404:
      description: Not found response
      content:
        text/plain:
          schema:
            title: Weather not found
            type: string
            example: Not found

Incorporate the Components Specification

In your terminal, retrieve the necessary files:

cd ~/Downloads   
git clone https://github.com/linuxacademy/content-apigee-api-engineer-exam

Change to the working file directory:
cd content-apigee-api-engineer-exam/crafting-openapi-spec
Open the components file in your text editor:
open openWeatherAPI-components.yaml
In your text editor, select the contents and copy it all.
In the Apigee spec editor, paste your copied contents after the security entry.
Click Save.
Enter a name for the spec: LA-Weather-Spec-1.
Click Save.

Test Your API Spec

We no longer provide the API Key, but you can easily acquire one by registering for free at https://openweathermap.org/home/sign_in.
Once registered and logged into the Open Weather site, go to API Keys to get your key, copy it, and return to the Apigee website.
Click Authorize.
and paste your key into the provided field
Click Authorize.
Click Close.
Expand Current weather data.
Click Try it out.
Enter a city name.
Click Execute.
Review response.
Continue testing with valid and invalid parameters.

Crafting an Apigee OpenAPI Spec

About this Hands-on Lab

Learning Objectives

Additional Resources

What are Hands-on Labs