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
Note that this documentation should relate to the API as a whole. To link a specific parameter to more documentation, you can add an
externalDocs object to the operation object, as noted in Operation objects section in Step 4 with paths.
View the Appearance in Swagger UI
Add the above code to the root level of your OpenAPI document in Swagger UI.
When you do, in the Swagger UI, a link appears after the API description along with other info about the API:
Here you can probably start to see challenges with integrating the Swagger UI output with the rest of your documentation. The
externalDocs object at least gives you a predictable place to link back to your other non-reference topics. 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 specification document. You can see the complete specification document here: https://idratherbewriting.com/learnapidoc/docs/rest_api_specifications/openapi_openweathermap.yml.
Here’s the specification document rendered by Swagger UI:
Try executing a request in the version above and look at the result. In the result, locate the
temp value in the
main object. Then take a break by going outside to evaluate whether the temperature outside matches the response.
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. For example, you could insert
https://petstore.swagger.io/v2/swagger.json (then click Explore) and it would show the Petstore API.
47/110 pages complete. Only 63 more pages to go...
Want to buy me lunch? Click the Donate button below to donate $10 through Paypal.