Step 8: The externalDocs object (OpenAPI tutorial)
externalDocs object lets you link to external documentation. You can also provide links to external docs in the
Example externalDocs object
Here’s an example of an
externalDocs: description: API Documentation url: https://openweathermap.org/api
In the Swagger UI, this link appears after the API description along with other info about the API.
See the related topic, Integrating Swagger UI with the rest of your docs for tips on how to integrate your Swagger UI output into your regular documentation.
Seeing the finished result
Now that we’ve completed all the steps in the tutorial, we’re finished building our OpenAPI document. You can see the end result here: docs/rest_api_specifications/openapi_weather.yml.
Here’s the specification document embedded in Swagger UI:
You can actually insert any valid path to an OpenAPI specification document into the “Explore” box in Swagger UI (assuming it’s using a version that supports your version of the spec), and it will display the content.
66/96 pages complete. Only 30 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.