Adding OpenAPI specification info to docs (ansible#4918)

DOCS: Document Access and Distribution of Platform Gateway OpenAPI Specification

https://issues.redhat.com/browse/AAP-57300

Affects `titles/central-auth`

Author: EMcWhinn

downstream/assemblies/platform/assembly-gw-settings.adoc

@@ -37,4 +37,10 @@ include::platform/proc-settings-gw-authentication.adoc[leveloffset=+2]
 
 include::platform/proc-gw-settings-insights-settings.adoc[leveloffset=+2]
 
+include::platform/con-gw-openAPI-specification.adoc[leveloffset=+1]
+
+include::platform/proc-gw-download-openAPI.adoc[leveloffset=+2]
+
+include::platform/proc-gw-access-interactive-docs.adoc[leveloffset=+2]
+
 include::platform/proc-settings-user-preferences.adoc[leveloffset=+1]

downstream/modules/platform/con-gw-openAPI-specification.adoc

@@ -0,0 +1,22 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="gw-openAPI-specification"]
+
+= Understanding the {Gateway} OpenAPI specification
+
+[role="_abstract"]
+{GatewayStart} serves as the single entry point for {PlatformNameShort}, unifying the user interface and routing all API traffic to services such as {ControllerName}, {EDAName}, and {HubName}.
+
+The OpenAPI specification provides a standardized, machine-readable definition of the unified API endpoints available through {Gateway}. 
+It is essential for external developers and automation engineers building reliable custom integrations.
+
+*Key roles of the specification*
+
+The OpenAPI specification ensures successful integration by fulfilling the following roles:
+
+* *Enables custom integrations*: Developers use the specification to understand endpoint structures, required parameters, and response schemas, which is needed for building custom applications and third-party tools.
+* *Ensures API longevity*: Integration with the {Gateway} API future-proofs custom applications against disruptions that might occur when legacy, direct-access component APIs are retired.
+* *Defines core functions*: The specification details endpoints that support fundamental operational and administrative functions, including:
+** Platform health, such as `/api/gateway/v1/status/`.
+** Activity monitoring, such as `/api/gateway/v1/activitystream/`.
+** Configuration management, such as authentication configuration and role-based access control assignments.

downstream/modules/platform/proc-gw-access-interactive-docs.adoc

@@ -0,0 +1,18 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="gw-access-interactive-docs"]
+
+= Accessing the interactive documentation (Rendered access)
+
+[role="_abstract"]
+{GatewayStart} provides an interactive, rendered version of the OpenAPI specification accessible directly in a web browser.
+
+.Procedure
+
+. Go to the documentation endpoint by using the following URL structure, replacing `$AAP_INSTANCE` with your hostname:
++
+[literal, options="nowrap" subs="+attributes"]
+----
+https://$AAP_INSTANCE/api/gateway/v1/docs/
+----
+. Explore the available API endpoints, view required parameters, and test interactions with the resources exposed by {Gateway}.

downstream/modules/platform/proc-gw-download-openAPI.adoc

@@ -0,0 +1,38 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="gw-download-openAPI"]
+
+= Downloading the {Gateway} OpenAPI specification
+
+[role="_abstract"]
+You can download the OpenAPI specification by using the `curl` command from the schema endpoint.
+
+.Prerequisites
+
+Token authentication is the recommended method for programmatic API use.
+
+. Create a Personal Access Token (PAT): From the navigation panel, select menu:{MenuAM}[Users], select your user, go to the *Tokens* tab, and click btn:[Create token].
+. Copy the generated token value. 
+Use this value as the `<OAUTH2_TOKEN_VALUE>` in the following commands.
+
+.Procedure
+
+* Retrieve the OpenAPI specification from the schema endpoint located at `https://$AAP_INSTANCE/api/gateway/v1/docs/schema/`, using one of the following methods:
+** Get the YAML specification (Default format): To download the specification as a YAML file, run the following command:
++
+[literal, options="nowrap" subs="+attributes"]
+----
+curl -o "gateway_openapi_spec.yaml" "https://$AAP_INSTANCE/api/gateway/v1/docs/schema/"
+----
++
+** Get the JSON specification (Optional format): To explicitly request the specification in JSON format, append `?format=json` to the URL path and run the following command:
++
+[literal, options="nowrap" subs="+attributes"]
+----
+curl -o "gateway_openapi_spec.json" "https://$AAP_INSTANCE/api/gateway/v1/docs/schema/?format=json"
+----
++
+[IMPORTANT]
+====
+Replace `$AAP_INSTANCE` with your {PlatformNameShort} hostname in the commands.
+====