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. Create an OpenAPI specification for this API.
If you don’t want to use that API (maybe it already has an OpenAPI specification document, or 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.
Depending on the API you choose to work with, you could potentially use this specification document as part of your portfolio.
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
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 openapi_sunrise_sunset.yml.
Note that the Sunrise and sunset times API doesn’t require authorization, so you can skip Step 6: security object.
You can use this OpenAPI specification document when working through the Swagger UI activity.
67/96 pages complete. Only 29 more pages to go...
If you would like to contribute back to say thank you for the API documentation course, click the Donate button below. Alternatively, to contribute content, such as a tutorial or a new section, contact me with your ideas. You can also submit a pull request in the GitHub repo to make your contribution. Even if you want to just fix a typo or add a sentence here and there, it's always welcome.
I'd Rather Be Writing Newsletter
Get new posts delivered straight to your inbox.