mirror of
https://github.com/elastic/kibana.git
synced 2025-04-23 17:28:26 -04:00
41a7e61855
# Backport This will backport the following commits from `main` to `8.16`: - [[OpenAPI] Add redocly lint configuration (#199360)](https://github.com/elastic/kibana/pull/199360) <!--- Backport version: 8.9.8 --> ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport) <!--BACKPORT [{"author":{"name":"Lisa Cawley","email":"lcawley@elastic.co"},"sourceCommit":{"committedDate":"2024-11-08T20:07:55Z","message":"[OpenAPI] Add redocly lint configuration (#199360)","sha":"907d19b7b82598ab070901f772323b71b583bc65","branchLabelMapping":{"^v9.0.0$":"main","^v8.17.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","v9.0.0","Feature:OAS","v8.16.0","backport:version","v8.17.0"],"number":199360,"url":"https://github.com/elastic/kibana/pull/199360","mergeCommit":{"message":"[OpenAPI] Add redocly lint configuration (#199360)","sha":"907d19b7b82598ab070901f772323b71b583bc65"}},"sourceBranch":"main","suggestedTargetBranches":["8.16","8.x"],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","labelRegex":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/199360","number":199360,"mergeCommit":{"message":"[OpenAPI] Add redocly lint configuration (#199360)","sha":"907d19b7b82598ab070901f772323b71b583bc65"}},{"branch":"8.16","label":"v8.16.0","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.x","label":"v8.17.0","labelRegex":"^v8.17.0$","isSourceBranch":false,"state":"NOT_CREATED"}]}] BACKPORT--> NOTE: I've also removed the serverless commands from the makefile, since they're not relevant to this branch. This PR will encounter CI failures until https://github.com/elastic/kibana/pull/199571 is merged.
116 lines
3.6 KiB
YAML
116 lines
3.6 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: false
|
|
operation-tag-defined: warn
|
|
operation-tags: warn
|
|
# Parameters
|
|
# Lower severity to allow optional path parameters
|
|
path-params: warn
|
|
# Responses
|
|
operation-success-response: warn
|
|
# Schema
|
|
oas3-schema: warn
|
|
oas2-schema: warn
|
|
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
|
|
property-description:
|
|
description: Properties should have descriptions.
|
|
message: "Each property should have a description"
|
|
severity: warn
|
|
given: $.components.schemas.*.properties.*
|
|
then:
|
|
field: description
|
|
function: defined
|
|
# 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[*][get,put,post,delete,options,head,patch,trace]
|
|
then:
|
|
field: summary
|
|
function: defined
|
|
operation-summary-length:
|
|
description: Operation summary should be between 5 and 45 characters
|
|
given: '$.paths[*][get,put,post,delete,options,head,patch,trace]'
|
|
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
|