mirror of
https://github.com/elastic/kibana.git
synced 2025-04-24 09:48:58 -04:00
7a2e7bef96
**Addresses:** https://github.com/elastic/kibana/issues/186356 **Relates to:** https://github.com/elastic/kibana/issues/184428 ## Summary This PR adds a merging JS script based on the utility implemented in https://github.com/elastic/kibana/issues/186356. Resulted OpenAPI bundle as committed in `oas_docs/output/kibana.serverless.bundled.yaml`. ## Details https://github.com/elastic/kibana/pull/188110 implements and exposes `merge` utility design to merge source OpenAPI specs without processing. It's has only a programmatic API. To merge OpenAPI specs it's required to add a JS script like below ```js const { merge } = require('@kbn/openapi-bundler'); (async () => { await merge({ sourceGlobs: [/* a list of source globs goes here */], outputFilePath: 'path/to/the/output/file.yaml', }); })(); ``` The JS script added in this PR includes source OpenAPI specs presented in `oas_docs/makefile` plus Security Solution OpenAPI specs based on https://github.com/elastic/kibana/issues/184428. **To run** the script use the following command from Kibana root folder ```bash node ./oas_docs/scripts/merge_serverless_oas.js ``` ## Known linting issues with Security Solution OpenAPI specs Running Spectral OpenAPI linter on the result bundle shows a number of errors caused by `no-$ref-siblings` rule. This caused by the current code generator implementation which requires `default` property to be set next to `$ref` though it's not correct for OpenAPI `3.0.3` while it's allowed in `3.1`. It seems that Bump.sh handles such cases properly though by properly showing a default value. We need to analyze the problem and decide if/when we should fix it. The rest of warnings look fixable and will be addressed in the next stage after setting up linter rules. ## Next steps Since `@kbn/openapi-bundler` package is tailored specifically for Kibana it should replace Redocly currently used to merge OpenAPI specs. It also means `oas_docs/makefile` should be superseded by JS script(s) using `merge` utility form `@kbn/openapi-bundler` package. `@kbn/openapi-bundler` SHOULD NOT replace OpenAPI linters since it doesn't perform thorough linting. It's good if we continue adopting `spectral-cli` for linting purposes.
105 lines
3.1 KiB
YAML
105 lines
3.1 KiB
YAML
extends: ['spectral:oas']
|
|
rules:
|
|
# Built-in rules
|
|
# Descriptions
|
|
oas3-parameter-description: warn
|
|
oas2-parameter-description: warn
|
|
tag-description: info
|
|
# Document info
|
|
info-contact: info
|
|
info-description: warn
|
|
info-license: warn
|
|
# Examples
|
|
oas3-valid-media-example: false
|
|
oas3-valid-schema-example: false
|
|
oas2-valid-media-example: false
|
|
# Operations
|
|
operation-operationId: error
|
|
operation-operationId-unique: error
|
|
operation-operationId-valid-in-url: error
|
|
operation-tag-defined: warn
|
|
operation-tags: warn
|
|
# Responses
|
|
operation-success-response: warn
|
|
# Schema
|
|
oas3-schema: error
|
|
oas2-schema: error
|
|
array-items: false
|
|
# Bump.sh handles $ref siblings. Documentation wise it's convenient to have properties like descriptions next to $ref.
|
|
no-$ref-siblings: off
|
|
# Tags
|
|
openapi-tags: warn
|
|
openapi-tags-alphabetical: info
|
|
# Turn off some built-in rules
|
|
operation-description: false
|
|
operation-singular-tag: false
|
|
# Custom rules
|
|
# Descriptions
|
|
avoid-problematic-words:
|
|
description: Ban certain words from descriptions
|
|
message: 'Use appropriate replacements for problematic terms'
|
|
severity: warn
|
|
given: '$..*.description'
|
|
then:
|
|
function: pattern
|
|
functionOptions:
|
|
notMatch: /(blacklist|whitelist|execute|kill)/i
|
|
# Examples
|
|
operation-success-examples:
|
|
formats: ['oas3_1']
|
|
description: Response code 200 should have at least one example.
|
|
message: 'Each response body should have a realistic example. It must not contain any sensitive or confidential data.'
|
|
severity: info
|
|
given: $.paths[*][*].responses.[200].content.[application/json]
|
|
then:
|
|
field: examples
|
|
function: defined
|
|
# Extensions
|
|
internal-extension:
|
|
description: Operations should not have x-internal extension.
|
|
message: 'Do not publish x-internal operations'
|
|
severity: error
|
|
given: $.paths[*][*]
|
|
then:
|
|
field: x-internal
|
|
function: undefined
|
|
# Operations
|
|
operation-summary:
|
|
description: Operations should have summaries.
|
|
message: 'Each operation should have a summary'
|
|
severity: error
|
|
recommended: true
|
|
given: $.paths[*][*]
|
|
then:
|
|
field: summary
|
|
function: defined
|
|
operation-summary-length:
|
|
description: Operation summary should be between 5 and 45 characters
|
|
given: '$.paths[*][*]'
|
|
then:
|
|
field: summary
|
|
function: length
|
|
functionOptions:
|
|
max: 45
|
|
min: 5
|
|
severity: warn
|
|
simple-verbs-in-summary:
|
|
given:
|
|
- '$.paths[*][*].summary'
|
|
then:
|
|
function: pattern
|
|
functionOptions:
|
|
notMatch: 'Retrieve|Return|List *'
|
|
severity: warn
|
|
description: Summaries should use common verbs.
|
|
message: 'Summaries should use common verbs like Get, Update, Delete whenever possible'
|
|
# NOTE: This one hiccups on acronyms so perhaps too noisy
|
|
# docs-operation-summary-sentence-case:
|
|
# description: Operation summary should be sentence cased
|
|
# given: "$.paths[*].[get,put,post,delete,options,head,patch,trace]"
|
|
# then:
|
|
# field: summary
|
|
# function: pattern
|
|
# functionOptions:
|
|
# match: /^[A-Z]+[^A-Z]+$/
|
|
# severity: warn
|