Crafting an Apigee OpenAPI Spec

30 minutes
  • 4 Learning Objectives

About this Hands-on Lab

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
  1. From the Apigee dashboard, choose Specs.
  2. Click the + Spec button and select New Spec.
Modify the Default Spec
  1. In the spec editor, change swagger: '2.0' to openapi: "3.0.2".
  2. Change info to the following:
    version: "2.5"
    title: OpenWeatherMap API
  3. Remove the host and schemes sections.
  4. Add the following section:
    - url:
  5. After servers, add:
    - app_id: []
  6. Change paths to the following:

    # This is a path endpoint. Change it.
    # This is a HTTP operation
      - 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
      - name: q
        in: query
        description: "**City name**. *Example: brooklyn,us*."
          type: string
      - name: zip
        in: query
        description: "**Zip code**. Search by zip code. *Example: 95050,us*."
          type: string
          description: Successful response
                $ref: '#/components/schemas/200'
          description: Not found response
                title: Weather not found
                type: string
                example: Not found 
Incorporate the Components Specification
  1. In your terminal, retrieve the necessary files:

    cd ~/Downloads   
    git clone
  2. Change to the working file directory:
    cd content-apigee-api-engineer-exam/crafting-openapi-spec

  3. Open the components file in your text editor:
    open openWeatherAPI-components.yaml

  4. In your text editor, select the contents and copy it all.

  5. In the Apigee spec editor, paste your copied contents after the security entry.

  6. Click Save.

  7. Enter a name for the spec: LA-Weather-Spec-1.

  8. Click Save.

Test Your API Spec
  1. We no longer provide the API Key, but you can easily acquire one by registering for free at

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

  3. Click Authorize.

  4. and paste your key into the provided field

  5. Click Authorize.

  6. Click Close.

  7. Expand Current weather data.

  8. Click Try it out.

  9. Enter a city name.

  10. Click Execute.

  11. Review response.

  12. Continue testing with valid and invalid parameters.

Additional Resources

Your organization is expanding their apps functionality to include gathering weather forecasts, globally. You've been asked to take the initial steps in shaping the OpenAPI specification to use the OpenWeatherMap API, ensuring you can get today's weather from any major city, anywhere in the world.

You’ll need to accomplish the following steps to complete your task:

  1. Create a new spec in Apigee.
  2. Modify the default spec.
  3. Test with SmartDocs.

What are Hands-on Labs

Hands-on Labs are real environments created by industry experts to help you learn. These environments help you gain knowledge and experience, practice without compromising your system, test without risk, destroy without fear, and let you learn from your mistakes. Hands-on Labs: practice your skills before delivering in the real world.

Sign In
Welcome Back!

Psst…this one if you’ve been moved to ACG!

Get Started
Who’s going to be learning?