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'toopenapi: "3.0.2". - Change
infoto the following:version: "2.5" title: OpenWeatherMap API - Remove the
hostandschemessections. - Add the following section:
servers: - url: https://api.openweathermap.org/data/2.5 - After
servers, add:security: - app_id: [] Change
pathsto 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
- In the spec editor, change
- Incorporate the Components Specification
In your terminal, retrieve the necessary files:
cd ~/Downloads git clone https://github.com/linuxacademy/content-apigee-api-engineer-examChange to the working file directory:
cd content-apigee-api-engineer-exam/crafting-openapi-specOpen the components file in your text editor:
open openWeatherAPI-components.yamlIn your text editor, select the contents and copy it all.
In the Apigee spec editor, paste your copied contents after the
securityentry.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.
