---
title: "Step 8: The externalDocs object (OpenAPI tutorial)"
date: 2026-10-03
description: "Download PDF The externalDocs object lets you link to external documentation. You can also provide links to external docs in the <code class="
canonical_url: https://idratherbewriting.com/learnapidoc/pubapis_openapi_step8_externaldocs_object
---

> For AI agents: a documentation index is available at https://idratherbewriting.com/llms.txt. Markdown versions of all pages are available by appending .md to any page URL.

# Step 8: The externalDocs object (OpenAPI tutorial)

[STEP 1:openapi object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step1_openapi_object.html)

→

[STEP 2:info object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step2_info_object.html)

→

[STEP 3:servers object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step3_servers_object.html)

→

[STEP 4: paths object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step4_paths_object.html)

→

[STEP 5:components object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step5_components_object.html)

→

[STEP 6:security object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step6_security_object.html)

→

[STEP 7:tags object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step7_tags_object.html)

→

[STEP 8:externalDocs object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step8_externaldocs_object.html)

→

[STEP 9:Other elements](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step9_other_elements.html)

[Download PDF](https://www.buymeacoffee.com/learnapidoc/e/146076)

The [`externalDocs` object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.1.md#externalDocumentationObject) lets you link to external documentation. You can also provide links to external docs in the `paths` object.

## Example externalDocs object

Here’s an example of an `externalDocs` object:

```yaml
externalDocs:
  description: Find out more about OpenWeatherMap API
  url: https://openweathermap.org/api
```

Note that this documentation should relate to the API as a whole. To link a specific operation to more documentation, you can add an `externalDocs` object to the operation object, as noted in the [Operation objects](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step4_paths_object.html#operation-objects) section in Step 4: The paths object.

If you get stuck, see the [sample OpenAPI spec here](https://idratherbewriting.com/docs/openapi_spec_and_generated_ref_docs/openapi_openweathermap.yml) 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:

![External documentation link](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/api/step8swaggerprogress.png)

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](https://idratherbewriting.com/learnapidoc/docconceptual.html). See [Integrating Swagger UI with the rest of your docs](https://idratherbewriting.com/learnapidoc/pubapis_combine_swagger_and_guide.html) 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](https://idratherbewriting.com/docs/openapi_spec_and_generated_ref_docs/openapi_openweathermap.yml).

Here’s the specification document rendered by Swagger UI:

[![](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/api/swagger_full_result.png)](https://idratherbewriting.com/assets/files/swagger/index.html)

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.