Activity: Create an OpenAPI specification document
The OpenAPI tutorial walked you through 8 steps in building the OpenAPI specification document. Now it’s your turn to practice building out an OpenAPI specification document on your own.
- Identify an API
- Follow the OpenAPI tutorial
- Make sure your spec validates
- Check your spec against mine
Identify an API
In an earlier activity, you found an open-source API project with some documentation needs. Try creating an OpenAPI specification for this API.
Depending on the API you choose to work with, you could potentially use this specification document as part of your portfolio.
If you don’t want to use that API (maybe it already has an OpenAPI specification document, or maybe there are other complications), you can use this simple Sunrise and sunset times API. This Sunrise and sunset times API doesn’t require authentication with requests, so it removes some of the more complicated authentication workflows.
Follow the OpenAPI tutorial
Go each step of the OpenAPI specification tutorial to build out the specification document:
- Step 1: openapi object
- Step 2: info object
- Step 3: servers object
- Step 4: paths object
- Step 5: components object
- Step 6: security object
- Step 7: tags object
- Step 8: externalDocs object
Note that the Sunrise and sunset times API doesn’t require authorization, so you can skip Step 6: security object.
Make sure your spec validates
Validate your specification document in the Swagger Editor. Execute a request to make sure it’s working correctly.
Check your spec against mine
If you get stuck or want to compare your spec with mine, see the specification document for the Sunrise and Sunset API here: https://idratherbewriting.com/learnapidoc/assets/files/swagger-sunrise-sunset/openapi_sunrise_sunset.yml.
You can use this OpenAPI specification document when working through the Swagger UI activity.
To see the Sunrise and Sunset specification document rendered by Swagger UI, just go to the Swagger UI Demo and paste in the link to the
openapi_sunrise_sunset.yml file into the Explore box.
66/108 pages complete. Only 42 more pages to go...
Want to buy me lunch? Click the Donate button below to donate $10 through Paypal.