Understanding the documentation structure

When you generate the Swagger documentation, Sterling™ Order Management System creates a well-organized folder structure that contains JSON specifications, interactive HTML pages, a main index file, and a search index.

The documentation is located at runtime/xapidocs/swaggerdoc/.

JSON folder (swaggerdoc/JSON/)

The JSON folder contains technical API specification files such as ycp.json, ycd.json, and omp.json. These machine-readable API definitions are used for tools and automation.

Use cases

  • Generate client code in Java, Python, JavaScript, and other languages.
  • Integrate with API management platforms.
  • Set up automated testing.

Developers, QA engineers, and integration specialists use these files.

HTML folder (swaggerdoc/HTML/)

The HTML folder contains interactive web pages for each API group such as ycp.html, ycd.html, and omp.html. These pages provide human-readable documentation with interactive features.

Key features

  • Expandable sections: Navigate through APIs easily.
  • Complete details: View field descriptions, required tags, and data types.
  • Examples: Review sample requests and responses.

Developers, business analysts, project managers, technical writers, and anyone who needs to understand the APIs use these pages.

index.html file (swaggerdoc/index.html)

The index.html file is the main entry point with navigation and search capabilities.

Features

  • Buttons for each API group
  • Global search bar to find APIs across all groups
  • Clean interface for easy browsing

How to use

  • Click a group button to view its APIs.
  • Use the search bar to find specific APIs instantly.
  • Bookmark this page as your starting point.

api-index.js file (swaggerdoc/api-index.js)

The api-index.js file is an auto-generated search index that powers the real-time search functionality. It contains a complete list of all APIs with names, methods, groups, and navigation links.

Note: The search index is automatically updated when you regenerate documentation. No manual editing is needed.

Best practices

To get the most out of the Swagger documentation, follow these best practices:

  • Start with index.html as your main entry point.
  • Use the search feature to find APIs quickly across all groups.
  • Import JSON files into Postman or similar tools for API testing.
  • Bookmark frequently used API group HTML pages for quick access.
  • Share the documentation URL with your development team.

For more information, see OpenAPI specification and Swagger UI.