Issue #15 - [FEATURE] Add format selection for OpenAPI document downloads

[rogelio-cmj]

Motivation

Users working with OpenAPI specifications often need to download the document in different formats depending on their tooling and workflow requirements. Currently, the API reference download functionality only provides the document in its original format without giving users a choice. This limitation forces users to manually convert between JSON and YAML formats using external tools, creating unnecessary friction in their workflow. By allowing users to download the specification in either format directly from the interface, we improve the developer experience and make the API reference more versatile and user-friendly.

Current Behavior

The download button in the API reference only downloads the OpenAPI document in its original format (either JSON or YAML, depending on how it was provided). Users cannot choose which format they want to download, and there's no indication of what format will be downloaded.

Reproduction Steps:

1. Open an API reference page with an OpenAPI specification
2. Locate the "Download OpenAPI Document" button in the interface
3. Click the download button
4. Observe: The document downloads in only one format (the original format)

Expected Behavior

Users should be able to download the OpenAPI specification in either JSON or YAML format, regardless of the original format. The interface should clearly indicate both format options and allow users to choose which format they prefer to download.

Acceptance Criteria:

• Two separate download buttons are displayed, one for JSON and one for YAML format
• Each download button clearly indicates the format (JSON or YAML) with a badge or label
• Clicking the JSON button downloads the specification in JSON format, even if the original was YAML
• Clicking the YAML button downloads the specification in YAML format, even if the original was JSON
• The downloaded files have the correct file extension (.json or .yaml) based on the selected format
• Unit tests verify the format conversion and download functionality for both formats

Steps To Test

1. Open an API reference page with a YAML OpenAPI specification
2. Click the "Download OpenAPI Document (json)" button
3. Verify the downloaded file has a .json extension and contains valid JSON
4. Click the "Download OpenAPI Document (yaml)" button
5. Verify the downloaded file has a .yaml extension and contains valid YAML
6. Repeat steps 1-5 with a JSON OpenAPI specification as the source
7. Run the test suite and verify all download-related tests pass
8. Verify the visual styling shows both buttons clearly with format badges
9. Test that hover effects and focus states work correctly on both buttons

Submission

Download https://cap.so/ to record your screen (use Studio mode). Export as an mp4, and drag and drop into an issue comment below.

Guide to submitting pull requests: https://hackmd.io/@timothy1ee/Hky8kV3hlx