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
description: API Documentation
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: The paths object.
If you get stuck, see the sample OpenAPI spec here for the fully working sample. This will help you spot and troubleshoot indentation or other errors.
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:
At this point, you can probably anticipate some challenges with integrating Swagger UI with the rest of your documentation. It seems that you will likely have two outputs and a semi-fragmented user experience. The
externalDocs object at least gives you a predictable place to link back to your other conceptual topics. See Integrating Swagger UI with the rest of your docs for more information on integration strategies.
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: 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 and evaluate whether the temperature outside matches the response.
You can insert any valid path to an OpenAPI specification document in the “Explore” box in Swagger UI (assuming the version of Swagger UI supports your OpenAPI version), and it will display the API documentation. For example, you could insert
https://petstore.swagger.io/v2/swagger.json (then click Explore) and it would show the Petstore API.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.
57/165 pages complete. Only 108 more pages to go.