github-mirrors/kibana
1
0
Fork 0
mirror of https://github.com/elastic/kibana.git synced 2025-06-28 11:05:39 -04:00
Code Issues Projects Releases Packages Wiki Activity
kibana/packages/kbn-securitysolution-endpoint-exceptions-common/docs/openapi
History
Maxim Palenov 845dd1fabb
[Security Solution] Add tags by OpenAPI bundler (#189621) 
**Resolves:** https://github.com/elastic/kibana/issues/183375

## Summary

This PR implements functionality assigning a provided tag to OpenAPI `Operation object`s in the result bundle. Specified tag is also added as the only root level OpenAPI tag. This approach allows to produce domain bundles having a single tag assigned. At the next step domain bundles are merged together into single Kibana bundle where tags will allow to properly display grouping at Bump.sh (API reference documentation platform).

## Details

Bump.sh (our new API reference documentation platform) uses OpenAPI tags for grouping API endpoints. It supports only one tag per endpoint.

This PR facilitates preparation of Kibana OpenAPI bundle to be uploaded to Bump.sh by implementing functionality assigning a provided tag to OpenAPI `Operation object`s in the result domain bundles. It's implemented by providing an optional configuration option `assignTag` whose format is OpenAPI Tag Object. When `assignTag` isn't specified the bundler merges existing tags.

## Example

Consider the following bundling configuration

```js
const { bundle } = require('@kbn/openapi-bundler');

bundle({
  // ...
  options: {
    assignTag: {
      name: 'Some Domain API tag name',
      description: 'Some Domain API description',
      externalDocs: {
        url: 'https://some-external-documentation-url',
        description: 'External documentation description',
    }
  },
});
```

and source OpenAPI specs

**spec1.schema.yaml**
```yaml
openapi: 3.0.3
info:
  title: Spec1
  version: '2023-10-31'
paths:
  /api/some_api:
    get:
      tags: ['Some local tag']
      responses:
        200:
          content:
            'application/json':
              schema:
                type: string
```

**spec2.schema.yaml**
```yaml
openapi: 3.0.3
info:
  title: Spec2
  version: '2023-10-31'
paths:
  /api/some_api:
    post:
      tags: ['Some global tag']
      responses:
        200:
          content:
            'application/json':
              schema:
                type: string
tags:
  - name: Some global tag
```

**spec2.schema.yaml**
```yaml
openapi: 3.0.3
info:
  title: Spec3
  version: '2023-10-31'
paths:
  /api/another_api:
    get:
      responses:
        200:
          content:
            'application/json':
              schema:
                type: string
```

After bundling above OpenAPI specs with the provided bundling script we'll get the following

**domain-bundle.schema.yaml**
```yaml
openapi: 3.0.3
info:
  title: Bundled document
  version: '2023-10-31'
paths:
  /api/some_api:
    get:
      tags: ['Some Domain API tag name']
      responses:
        200:
          content:
            'application/json':
              schema:
                type: string
    post:
      tags: ['Some Domain API tag name']
      responses:
        200:
          content:
            'application/json':
              schema:
                type: string
  /api/another_api:
    get:
      tags: ['Some Domain API tag name']
      responses:
        200:
          content:
            'application/json':
              schema:
                type: string
tags:
  - name: Some Domain API tag name
    description: Some Domain API description
    externalDocs:
      url: 'https://some-external-documentation-url'
      description: External documentation description
```
2024-08-02 16:41:49 +02:00
..
ess [Security Solution] Add tags by OpenAPI bundler (#189621) 2024-08-02 16:41:49 +02:00
serverless [Security Solution] Add tags by OpenAPI bundler (#189621) 2024-08-02 16:41:49 +02:00