{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["API descriptions can be rather dry and factual, producing reference documentation that is accurate but can still fail to bridge the gap between API interface and happy, productive API consumers. Adding examples to OpenAPI can go a long way to helping users understand what they can do, and how to do it. There's no replacement for quickstart guides, tutorials, and other documentation of course - but richer examples in the OpenAPI descriptions can feed documentation and other downstream tools to get users up and running fast."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The first step is to include examples for as many aspects of your OpenAPI as you can. Headers, parameters, request bodies and responses all benefit from appropriate examples. This article shows how to add examples to your API descriptions, and how to get the examples to do a little more work along the way."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"choose-data-that-connects","__idx":0},"children":["Choose data that connects"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Choosing meaningful data takes time and energy, but it produces results. There are very few situations where the string ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"foo\""]}," or the string ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"string\""]}," truly help a user to reach their destination with efficiency and delight. In the example below you can see some of the common fields used in the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://github.com/Redocly/museum-openapi-example"},"children":["Museum API"]}," and the example values used to help the user get the correct data in each field."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"    EventId:\n      description: Identifier for a special event.\n      type: string\n      format: uuid\n      example: 3be6453c-03eb-4357-ae5a-984a0e574a54\n    EventPrice:\n      description: Price of a ticket for the special event\n      type: number\n      format: float\n      example: 25\n    publishedDate:\n      description: ISO-formatted date value.\n      type: string\n      format: date\n      example: 2024-02-28\n    Email:\n      description: Email address for ticket purchaser.\n      type: string\n      format: email\n      example: museum-lover@example.com\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Don't be too serious with your examples! It's good practice to use a ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://www.iana.org/help/example-domains"},"children":["reserved example like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["example.com"]}]}," for URLs and email addresses, but here we've used ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["museum-lover@example.com"]}," and it always makes me smile!"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Especially if your API has multiple similar fields, use example data as well as meaningful field descriptions to direct the user's attention. For example. we use start dates that are earlier than end dates. You could also use data such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customer@example.com"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accounts-department@example.com"]}," to distinguish multiple email fields."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"add-example-values-for-object-properties","__idx":1},"children":["Add example values for object properties"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more complex values, such as objects, a great way to start is to add an example for each property. Depending which tools consume the OpenAPI description, they may make use of these. The following example shows a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SpecialEvent"]}," schema with multiple object properties, where each property has an example field."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"    SpecialEvent:\n      description: Special museum events with ticketing.\n      properties:\n        name:\n          description: Name of the special event\n          type: string\n          example: Fossil lecture\n        location:\n          description: Location where the special event is held\n          type: string\n          example: Lecture theatre\n        eventDescription:\n          description: Description of the special event\n          type: string\n          example: Our panel of experts will share their favorite fossils and explain why they are so great.\n        dates:\n          description: List of planned dates for the special event\n          type: array\n          items:\n            type: string\n            format: date\n            example: 2024-03-29\n        price:\n          description: Price of a ticket for the special event\n          type: number\n          format: float\n          example: 12.50\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These values are combined by tools such as ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://github.com/Redocly/redoc"},"children":["Redoc"]}," to show an example to the user of how the payload looks."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/redoc-response-schema-675be1ea50f508c8.png","alt":"Redoc renders the SpecialEvent schema in API reference documentation"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"use-multiple-examples-for-responses","__idx":2},"children":["Use multiple examples for responses"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We're going to skip the backstory of how it is possible that OpenAPI has both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["example"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["examples"]}," as valid keywords (",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://philsturgeon.com/openapi-examples/"},"children":["Phil's writeup is good"]}," if you are curious). Suffice to say: being able to supply multiple examples is brilliant, and especially useful when there are a few different possible responses to an endpoint."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example shows the Museum API returning two example payloads:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"      responses:\n        \"200\":\n          description: Success\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/GetMuseumHoursResponse\"\n              examples:\n                default:\n                  summary: Museum opening hours\n                  value:\n                    - publishedDate: \"2023-09-11\"\n                      timeOpen: \"09:00\"\n                      timeClose: \"18:00\"\n                    - publishedDate: \"2023-09-12\"\n                      timeOpen: \"09:00\"\n                      timeClose: \"18:00\"\n                    - publishedDate: \"2023-09-13\"\n                      timeOpen: \"09:00\"\n                      timeClose: \"18:00\"\n                    - publishedDate: \"2023-09-17\"\n                      timeOpen: \"09:00\"\n                      timeClose: \"18:00\"\n                closed:\n                  summary: The museum is closed\n                  value: []\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By describing the possible different payloads that the API can return, API consumers can be confident that they can test edge cases. In the example of the Museum API opening hours, if the museum is closed then there are no opening hours for a particular date entry. Adding a separate example showing an empty array if there are no opening hours in the date range specified gives users a clear message of what happens in that situation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more complex APIs, returning multiple response examples becomes even more useful. For example in an ecommerce system, an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order"]}," schema might have diffferent data in it depending if the order is already paid for, delivered, and so on. Showing the examples goes beyond showing a list of optional data fields to clearly illustrate what the API consumer can expect."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"add-linting-for-examples","__idx":3},"children":["Add linting for examples"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://github.com/Redocly/redocly-cli/"},"children":["Redocly CLI"]}," is a widely-used tool for linting OpenAPI descriptions; it has specific rules available to help check that the examples in an OpenAPI description are present and valid. Read more about ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"../docs/cli/configuration/reference/rules"},"children":["setting up your own linting rules"]}," and try enabling these example-specific rules in your own projects:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/rules/oas/no-invalid-parameter-examples"},"children":["no-invalid-parameter-examples"]},": Parameter examples must match declared schema types."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/rules/oas/scalar-property-missing-example"},"children":["scalar-property-missing-example"]},": All required scalar (non-object) properties must have examples defined."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/rules/oas/no-invalid-schema-examples"},"children":["no-invalid-schema-examples"]},": Schema examples must match declared types."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/rules/oas/no-invalid-media-type-examples"},"children":["no-invalid-media-type-examples"]},": Example request bodies must match the declared schema."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples-are-worth-a-thousand-words","__idx":4},"children":["Examples are worth a thousand words"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We're documentation fanatics, so we'd probably say that you can write the thousand words as well, but having clear examples throughout your API description takes your API user experience to the next level. This post showed how you can add examples to the various aspects of an OpenAPI file, and gave some tips for picking example values to nudge your users in the right direction."]}]},"frontmatter":{"template":"../@theme/templates/BlogPost","title":"Better examples for better API experience","description":"Set API consumers up for success with good and meaningful OpenAPI examples.","seo":{"title":"Better examples for better API experience","description":"Set API consumers up for success with good and meaningful OpenAPI examples."},"author":"lorna-mitchell","publishedDate":"2024-02-28","categories":["api-specifications:openapi","api-lifecycle:design"],"image":"Redocly_blog_3.jpg"},"tagList":[],"title":"Better examples for better API experience","lastModified":"2026-10-01T07:04:24.000Z"}