Add OpenAPI Download Options: JSON & YAML

by Admin 42 views
Issue #15 - [FEATURE] Add format selection for OpenAPI document downloads

Hey guys! This is all about adding a super handy feature to our API reference downloads. Right now, you can only download the OpenAPI document in its original format, which can be a pain if you need it in a different format. Let's dive into why this is important, what we're aiming for, and how we're going to make it happen!

Motivation

OpenAPI specifications are essential, and users often need them in different formats like JSON and YAML based on their tools and workflows. Currently, the API reference download feature only offers the document in its original format. This forces users to manually convert between JSON and YAML using external tools, which is annoying and time-consuming. By allowing users to download the specification in either format directly from the interface, we're seriously leveling up the developer experience and making the API reference way more versatile and user-friendly. This enhancement streamlines workflows and ensures that developers can seamlessly integrate API specifications into their projects, regardless of the format they require. Providing both JSON and YAML options caters to a broader audience, accommodating various preferences and toolchain requirements. The direct download feature eliminates the need for third-party conversion tools, reducing the risk of data corruption or compatibility issues during format transformation.

Moreover, having the flexibility to choose the download format simplifies collaboration among team members who might prefer different formats. It also aligns with best practices in API development, where offering multiple formats for specifications is considered a standard feature. By implementing this enhancement, we are not only improving the immediate user experience but also investing in the long-term usability and adoption of our API reference. This feature addresses a common pain point for developers, making it easier for them to work with our APIs and integrate them into their systems efficiently. The ability to switch between formats on demand fosters a more agile development environment, allowing developers to adapt quickly to changing project requirements and tool preferences.

Furthermore, this feature enhances the overall professionalism and polish of our API documentation. It demonstrates our commitment to providing a comprehensive and user-centric experience. By catering to the diverse needs of our user base, we reinforce our position as a reliable and developer-friendly platform. The added convenience of format selection reflects our understanding of the challenges developers face daily and our proactive approach to addressing them. This improvement is also beneficial for educational purposes, as it allows users to easily explore and compare the JSON and YAML representations of the same API specification. This can be particularly helpful for developers who are new to OpenAPI and want to learn the nuances of each format.

Current Behavior

Right now, 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 can't choose which format they want to download, and there's no indication of what format will be downloaded. Basically, what you see is what you get, and that's not always ideal.

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

What we want is for users to be able to download the OpenAPI specification in either JSON or YAML format, no matter the original format. The interface should clearly show both format options and let users pick their preferred format.

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

This enhancement aims to provide a more flexible and user-friendly experience for developers working with OpenAPI specifications. By enabling users to download the document in their preferred format, we reduce the need for external conversion tools and streamline their workflow. The inclusion of clear format indicators and proper file extensions ensures that users can easily identify and manage the downloaded files. Comprehensive unit tests will validate the correctness and reliability of the format conversion and download functionality. This feature not only addresses a common pain point but also aligns with best practices in API development, where offering multiple formats for specifications is considered a standard feature. The availability of both JSON and YAML options caters to a broader audience, accommodating various preferences and toolchain requirements. This improvement will contribute to a more efficient and intuitive API reference experience, empowering developers to seamlessly integrate our APIs into their projects.

Furthermore, this feature will simplify collaboration among team members who may prefer different formats, promoting a more cohesive and productive development environment. The ability to switch between formats on demand fosters a more agile development environment, allowing developers to adapt quickly to changing project requirements and tool preferences. This improvement is also beneficial for educational purposes, as it allows users to easily explore and compare the JSON and YAML representations of the same API specification. This can be particularly helpful for developers who are new to OpenAPI and want to learn the nuances of each format. By implementing this enhancement, we are not only improving the immediate user experience but also investing in the long-term usability and adoption of our API reference.

Steps To Test

Alright, here's how we're going to test this bad boy:

  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

To show off your awesome work, record your screen using Cap.so (use Studio mode), export it as an MP4, and drag and drop it into an issue comment below. This helps us quickly review and appreciate your contribution!

Don't forget to check out the guide to submitting pull requests: https://hackmd.io/@timothy1ee/Hky8kV3hlx

Let's make this API reference download feature super flexible and user-friendly. Your contributions are highly valued, and we're excited to see what you come up with! Happy coding, guys!