Skip to main content

Crafting an Apigee OpenAPI Spec

Hands-On Lab

 

Photo of Joseph Lowery

Joseph Lowery

Google Cloud Training Architect II in Content

Length

00:30:00

Difficulty

Beginner

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.

What are Hands-On Labs?

Hands-On Labs are scenario-based learning environments where learners can practice without consequences. Don't compromise a system or waste money on expensive downloads. Practice real-world skills without the real-world risk, no assembly required.

Crafting an Apigee OpenAPI Spec

Introduction

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.

Accessing Our Apigee Hands-On Labs

In order to do this hands-on lab, you'll need an Apigee account. Google Cloud Apigee offers free evaluation accounts, with which you can experience all of our hands-on labs. Visit cloud.google.com/apigee, and click Try it free to sign up.

Because Apigee is part of Google Cloud, our hands-on labs are under the Google Cloud umbrella. However, for this lab, you don't need to use the GCP account provided on the lab page. All the work is done through your Apigee account, so you can ignore the credentials section.

Create New Specification

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

Modify the Default Spec

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

> Note: You can ignore the errors that appear while we're making changes. By the time we're done, they'll be resolved.

  1. Change info to the following:

    version: "2.5"
    title: OpenWeatherMap API
    description: "Get current weather"
  2. Remove the host and schemes sections.

  3. Where the host and schemes sections used to be, add the following section:

    servers:
    - url: https://api.openweathermap.org/data/2.5
  4. After servers, add:

    security:
    - app_id: []
  5. 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."
          operationId: CurrentWeatherData
          # This is array of GET operation parameters
          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
  1. Start a new line, and back your cursor all the way up to the left.

Incorporate the Components Specification

  1. In your terminal, retrieve the necessary files:

    cd ~/Downloads   
    git clone https://github.com/linuxacademy/content-apigee-api-engineer-exam
  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. Check that it did not add or remove any spaces in front of the lines. You may need to tweak the spacing.

  6. Click Save.

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

  8. Click Save.

Test Your API Spec

  1. Click Authorize.
  2. In the dialog, copy the provided API key and enter it in the value field; alternatively, you can enter your own OpenWeatherAPI key.
  3. Click Authorize.
  4. Click Close.
  5. Expand Current weather data.
  6. Click Try it out.
  7. Enter a city name.
  8. Click Execute.
  9. Review response.
  10. Continue testing with valid and invalid parameters.

Conclusion

Congratulations on successfully completing this hands-on lab!