[DOCS] Add openAPI specification for APM agent configuration endpoints (

#12948)

Relates to #12903

This PR updates the OpenAPI specification to include details from https://www.elastic.co/guide/en/observability/current/apm-api-config.html

Related to the outstanding issue #12904, this PR re-adds the original file from #12862

docs/spec/openapi/apm-openapi.yaml

@@ -0,0 +1,178 @@
+openapi: 3.1.0
+info:
+  title: APM Server
+  description: OpenAPI schema for APM Server APIs
+  version: "0.1"
+  license:
+    name: Elastic License 2.0
+    url: https://www.elastic.co/licensing/elastic-license
+  contact:
+    name: APM Team
+servers:
+  - url: /
+tags:
+  - name: agent config
+    description: APIs that query the APM Server for configuration changes.
+    x-displayName: APM agent configuration
+  - name: server info
+    description: APIs that query general APM Server information.
+    x-displayName: APM server information
+paths:
+  /:
+    get:
+      summary: Get general server information
+      description: |
+        This lightweight endpoint is useful as a server up/down health check.
+        To configure authenticated access to the APM server, the instructions at [APM API key](https://www.elastic.co/guide/en/observability/current/api-key.html) or [APM Secret Token](https://www.elastic.co/guide/en/observability/current/secret-token.html) must be followed to configure the correct permissions for APM access.
+      operationId: getServerHealth
+      tags:
+        - server info
+      responses:
+        '200':
+          $ref: '#/components/responses/200_server_info'
+    post:
+      summary: Get general server information
+      operationId: postServerHealth
+      tags:
+        - server info
+      responses:
+        '200':
+          $ref: '#/components/responses/200_server_info'
+  /config/v1/agents:
+    get:
+      summary: Get agent configuration changes
+      description: >
+        To configure authenticated access to the APM server, the instructions at [APM API key](https://www.elastic.co/guide/en/observability/current/api-key.html) or [APM Secret Token](https://www.elastic.co/guide/en/observability/current/secret-token.html) must be followed to configure the correct permissions for APM access.
+      operationId: getAgentConfig
+      tags:
+        - agent config
+      parameters:
+        - in: query
+          name: service.name
+          required: true
+          schema:
+            type: string
+        - in: query
+          name: service.environment
+          schema:
+            type: string
+      responses:
+        '200':
+          description: A successful response. 
+          content:
+            application/json:
+              schema:
+                type: object
+    post:
+      summary: Get agent configuration changes
+      description: >
+        To configure authenticated access to the APM server, the instructions at [APM API key](https://www.elastic.co/guide/en/observability/current/api-key.html) or [APM Secret Token](https://www.elastic.co/guide/en/observability/current/secret-token.html) must be followed to configure the correct permissions for APM access.
+      operationId: postAgentConfig
+      tags:
+        - agent config
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - service
+              properties:
+                CAPTURE_BODY:
+                  type: string
+                  example: off
+                service:
+                  type: object
+                  required:
+                    - name
+                  properties:
+                    environment:
+                      type: string
+                      example: all
+                    name:
+                      type: string
+                      example: test-service
+              additionalProperties: true
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  capture_body:
+                   type: string
+                   enum: [ off, errors, transactions, all ]
+                   description: >
+                    For transactions that are HTTP requests, the agent can optionally capture the request body (for example, POST variables).
+                    For transactions that are initiated by receiving a message from a message broker, the agent can capture the textual message body.
+                   example: off
+                  transaction_max_spans:
+                    type: integer
+                    minimum: 0
+                    description: The maximum number of spans that are recorded per transaction.
+                    example: 500
+                  transaction_sample_rate:
+                    type: number
+                    format: float
+                    minimum: 0.0
+                    maximum: 1.0
+                    description: The agent samples transactions at this rate.
+                    example: 0.3
+                additionaProperties: true
+        '403':
+          description: APM Server is configured to fetch agent configuration from Elasticsearch but the configuration is invalid.
+        '503':
+          description: APM Server is starting up or Elasticsearch is unreachable.
+  /config/v1/rum/agents:
+    get:
+      summary: Get RUM agent configuration changes
+      description: >
+        To configure authenticated access to the APM server, the instructions at [APM API key](https://www.elastic.co/guide/en/observability/current/api-key.html) or [APM Secret Token](https://www.elastic.co/guide/en/observability/current/secret-token.html) must be followed to configure the correct permissions for APM access.
+      operationId: getRumAgentConfig
+      tags:
+        - agent config
+      responses:
+        '200':
+          description: Successful response.
+components:
+  securitySchemes:
+    apiKeyAuth:
+      type: apiKey
+      in: header
+      name: Authorization
+      description: 'e.g. Authorization: ApiKey base64AccessApiKey'
+    secretToken:
+      type: http
+      scheme: bearer
+      bearerFormat: Secret token
+  responses:
+    200_server_info:
+      description: A successful response indicates that the server is up.
+      content:
+        application/json:
+          schema:
+            description: If an API key or a secret token is passed along with the request, the response payload includes some information about the APM server.
+            type: object
+            properties:
+              build_date:
+                type: string
+                format: time-date
+              build_sha:
+                type: string
+              publish_ready:
+                type: boolean
+              version:
+                type: string
+          examples:
+            getServerHealthAuthResponse:
+              summary: Example APM Server information request with a secret token
+              value:
+                build_date: '2021-12-18T19:59:06Z'
+                build_sha: 24fe620eeff5a19e2133c940c7e5ce1ceddb1445
+                publish_ready: true
+                version: 8.12.2
+security:
+  - apiKeyAuth: [ ]
+  - secretToken: [ ]