Streamlining Your ESHOPMAN Admin API Documentation: A Critical Fix for OAS Tag Merging

Streamlining Your ESHOPMAN Admin API Documentation: A Critical Fix for OAS Tag Merging

For ESHOPMAN developers extending the platform's robust Admin API with custom functionalities, maintaining accurate and valid API documentation is paramount. Our community recently identified and addressed a critical issue within ESHOPMAN's API documentation generation tool, specifically concerning how OpenAPI Specification (OAS) tags are merged when customizing your API definitions. This insight highlights the problem, its impact, and the elegant solution now integrated into ESHOPMAN's developer toolkit.

The Challenge: Unexpected OAS Tag Behavior

When developers use ESHOPMAN's API documentation tool to merge a base OpenAPI specification file (e.g., for custom Admin API routes) with ESHOPMAN's core API documentation, an unexpected behavior in tag merging was observed. The utility responsible for combining these specifications, which is crucial for a complete and accurate API reference, exhibited inconsistent results based on the number of tags declared in the base file.

Impact on ESHOPMAN Developers

This bug presented several challenges for developers aiming to provide comprehensive documentation for their custom ESHOPMAN Admin API endpoints:

  • Missing Core Tags: If a base specification file declared no custom tags, all of ESHOPMAN's core API tags (like 'Orders' or 'Products') were inadvertently dropped from the final merged output, leading to incomplete documentation.
  • Duplicate Tags and Validation Errors: When a base file included two or more custom tags, ESHOPMAN's core tags would be duplicated in the merged specification. This not only bloated the documentation but also caused critical OpenAPI Specification (OAS) validation failures, as tags must be unique. In some cases, this even led to out-of-memory errors during the documentation generation process.
  • Inconsistent Overrides: Even when a custom tag in the base file was intended to override an ESHOPMAN core tag (e.g., providing a custom description for 'Orders'), both the original and the overridden versions would appear, further complicating documentation accuracy.

Essentially, developers were limited to defining only a single custom tag group in their base file without encountering these issues, severely restricting the organization and description of their extended Admin API functionalities.

The Solution: A Refined Merging Algorithm

Thanks to a proactive community member, a robust and efficient solution has been proposed and adopted. The fix lies in a revised merging algorithm within ESHOPMAN's API documentation utility. Instead of a nested loop that could lead to duplications, the new approach uses a Map-based strategy to ensure that:

  • Each ESHOPMAN core tag appears exactly once.
  • Any custom tag from the base file with a matching name correctly replaces the ESHOPMAN core tag.
  • All other unique custom tags from the base file are appended to the final list, ensuring comprehensive documentation without redundancy.

Example of Expected vs. Actual Behavior (before fix):

Consider the merging of ESHOPMAN's core tags ('Orders', 'Products') with various base tag configurations:

// ESHOPMAN core tags: ["Orders","Products"] 

// Before fix:
base tags: []                         -> merged: [] // ESHOPMAN tags dropped
base tags: ["Custom A"]               -> merged: ["Orders","Products","Custom A"] // Correct
base tags: ["Custom A","Custom B"]    -> merged: ["Orders","Orders","Products","Products","Custom A","Custom B"] // Duplicates
base tags: ["Orders","Custom A"]      -> merged: ["Orders","Orders","Products","Products","Custom A"] // Duplicates, incorrect override

The Proposed Corrected Logic:

The refined logic ensures accurate and validated OAS output:

const sourceByName = new Map(sourceTags.map((tag) => [tag.name, tag]))
const targetNames = new Set(targetTags.map((tag) => tag.name))
const combinedTags: TagObject[] = targetTags.map(
  (tag) => sourceByName.get(tag.name) ?? tag
)
for (const tag of sourceTags) {
  if (!targetNames.has(tag.name)) {
    combinedTags.push(tag)
  }
}
targetOAS.tags = combinedTags

This approach guarantees that ESHOPMAN developers can now confidently define and merge their custom Admin API documentation, regardless of the complexity or number of custom tags, without encountering validation errors or incomplete specifications.

Conclusion:

This swift resolution underscores the strength of the ESHOPMAN community and our commitment to providing a seamless headless commerce experience. Developers can now leverage ESHOPMAN's Admin API with even greater flexibility, knowing their documentation will always be accurate and valid for their HubSpot-powered storefronts.

Start with the tools

Explore migration tools

See options, compare methods, and pick the path that fits your store.

Explore migration tools