docs: API & Event stream documentation and format changes #5798 #5801

[gayanath8]

Issue Labels

#5798
#5801

Requirements

• Audit all existing Guardian API endpoints and identify documentation gaps.
• Improve documentation for every existing API endpoint, including: endpoint URL, HTTP method, authentication requirements, request payload schema with field descriptions, response payload schema, and error codes.
• Add documentation for any API endpoints that are currently undocumented.
• Generalize and clearly document each supported API block's execution payload structure.
• Keep provisions in the documentation for dynamic fields defined by users within policies.
• Provide example request/response pairs for common workflows.
• Update the Application Events Module documentation page with comprehensive, current information about all available event types, their payloads, and usage patterns.
• Fill in the External Events documentation page with all current event types supported by Guardian's event stream.
• Each event type should be documented with: event name, trigger condition, payload structure, and example usage.
• Include guidance on how external systems should subscribe to and consume these events.

Summary of Changes

• Added documentation for previously undocumented API endpoints
• Introduced the Policy Block API Execution Payloads guide
• Reformatted all existing API documentation
• Filled documentation gaps and restructured event stream docs
• Corrected and expanded the execution payloads guide with source-verified block entries
• Updated SUMMARY.md to reflect the reorganized structure.

[Pyatakov]

Hey @gayanath8, I've noticed that not all documentation paths have been updated. For example (I just picked a couple), docs/guardian/standard-registry/schemas/system-schema-apis/ and docs/guardian/standard-registry/schemas/schema-creation-using-apis/. Please make sure all APIs are covered.
Additionally, not all existing APIs are documented. In particular, there is no documentation for Api-Version: 2 of the tools/, schemas/, and policies/ endpoints. You can find them in the api-gateway source code using the name: 'Api-Version' search.

[gayanath8]

Hey @gayanath8, I've noticed that not all documentation paths have been updated. For example (I just picked a couple), docs/guardian/standard-registry/schemas/system-schema-apis/ and docs/guardian/standard-registry/schemas/schema-creation-using-apis/. Please make sure all APIs are covered. Additionally, not all existing APIs are documented. In particular, there is no documentation for Api-Version: 2 of the tools/, schemas/, and policies/ endpoints. You can find them in the api-gateway source code using the name: 'Api-Version' search.

Thanks for the review feedback @Pyatakov . I've addressed mentioned points:

• Converted all documentation under the flagged paths from legacy GitBook {% swagger %} format to clean markdown with tables and JSON examples.
• Searched the api-gateway source for all @Version('2') decorated handlers and added documentation for every missing one: GET /schemas, GET /tools, GET /tokens, GET /policies, GET /tags/schemas, GET /schemas/system/{username}, GET /modules, GET /artifacts, POST /policies/{policyId}/dry-run/user, POST /projects/compare/documents, and POST /contracts.
• Corrected several identified errors in the docs, wrong HTTP methods, incorrect permission names (e.g. SCHEMAS_SCHEMA_* vs SCHEMAS_SYSTEM_SCHEMA_*), wrong response codes, and one incorrect endpoint path (GET /map/sh not /map/key).
• Updated related docs to reflect changes introduced in PR. feat: Add Block Completion Events to the Event Stream #5799 #6043