Скачать или смотреть How to Convert OpenAPI Response Example Content to Simple JSON for Code Highlighting

Learn how to convert OpenAPI response examples into simple JSON objects ready for displaying in code highlighters like `highlight.js`.
---
This video is based on the question https://stackoverflow.com/q/77528142/ asked by the user 'Ilyas Khametov' ( https://stackoverflow.com/u/6375607/ ) and on the answer https://stackoverflow.com/a/77531741/ provided by the user 'Ilyas Khametov' ( https://stackoverflow.com/u/6375607/ ) at 'Stack Overflow' website. Thanks to these great users and Stackexchange community for their contributions.

Visit these links for original content and any more details, such as alternate solutions, comments, revision history etc. For example, the original title of the Question was: How to convert OpenAPI response example content to simple JSON ready for code highlighter?

Also, Content (except music) licensed under CC BY-SA https://meta.stackexchange.com/help/l...
The original Question post is licensed under the 'CC BY-SA 4.0' ( https://creativecommons.org/licenses/... ) license, and the original Answer post is licensed under the 'CC BY-SA 4.0' ( https://creativecommons.org/licenses/... ) license.

If anything seems off to you, please feel free to write me at vlogize [AT] gmail [DOT] com.
---
Introduction to OpenAPI and Highlight.js

When developing APIs using OpenAPI, you might come across the need to showcase response examples clearly. Specifically, you may need to convert complex OpenAPI response schemas into simplified JSON objects that can be easily used in code highlighting libraries such as highlight.js. This article will guide you through the process and provide practical solutions to achieve this.

The Challenge

In an OpenAPI specification, responses can often include complex structures, including references to other schemas via $ref. For instance, a typical response may look like this:

[[See Video to Reveal this Text or Code Snippet]]

In this schema, we see references to other components, making it challenging to derive a straightforward JSON object for display. What we want is to convert this complexity into simple, ready-to-display JSON.

Solution: Using Third-Party Packages

After some exploration, we found two powerful packages that can facilitate this conversion process:

@apidevtools/swagger-parser: This tool allows us to parse the OpenAPI spec and replace $ref entries with the corresponding values from the specification components.

openapi-sampler: This package generates sample data based on the OpenAPI payload/response schema and prepares it for highlighting.

Step 1: Dereference the OpenAPI Spec

To replace $ref values, we need to dereference the OpenAPI specification. Here's how to do that using @apidevtools/swagger-parser:

[[See Video to Reveal this Text or Code Snippet]]

The dereference method fetches the complete structure of the spec, resolving any references directly within the response schemas.

Step 2: Generate Sample Data

Now that we have a dereferenced schema, we can generate sample data using the openapi-sampler package. Here's how:

[[See Video to Reveal this Text or Code Snippet]]

Understanding the Code

Dereferencing: The first block of code fetches the full schema, resolving any $ref references.

Generating Samples: The second code block prepares a sampling of the response schema tailored to capture the defined structure, making it ready for use in code highlighters like highlight.js.

Conclusion

By leveraging the power of @apidevtools/swagger-parser and openapi-sampler, you can easily convert complex OpenAPI response formats into simple JSON structures. This simplifies the process of displaying code examples in your documentation or guides, ensuring clarity and enhanced readability for your audience.

Now you have the steps and tools to convert OpenAPI responses effectively, allowing for better documentation and presentation in your projects!