[DOCS] Add api-docs to makefile; add linting rules (#13664) (#13679)

* Add api-docs to makefile; add linting rules

* Turn off misleading array-errors linting rule

(cherry picked from commit edb2785)

Co-authored-by: Lisa Cawley <[email protected]>

Makefile

@@ -326,3 +326,13 @@ smoketest/all/cleanup:
 		echo "-> Cleanup $${test_dir} smoke tests..."; \
 		$(MAKE) smoketest/cleanup TEST_DIR=$${test_dir}; \
 	done
+
+.PHONY: api-docs
+api-docs: ## Generate bundled OpenAPI documents
+	@npx @redocly/cli bundle "docs/spec/openapi/apm-openapi.yaml" --ext yaml --output "docs/spec/openapi/bundled.yaml"
+	@npx @redocly/cli bundle "docs/spec/openapi/apm-openapi.yaml" --ext json --output "docs/spec/openapi/bundled.json"
+
+.PHONY: api-docs-lint
+api-docs-lint: ## Run spectral API docs linter
+	@npx @stoplight/spectral-cli lint "docs/spec/openapi/bundled.yaml" --ruleset "docs/spec/openapi/.spectral.yaml"
+

docs/README.md

@@ -9,10 +9,10 @@
 > * **Sample data sets** that are injected into the docs are in the [`docs/data/`](/docs/data/) directory.
 > * **Specifications** that are injected into the docs are in the [`docs/spec/`](/docs/spec/) directory.
 
-To generate the bundled files in the [`docs/spec/openapi`](/docs/spec/openapi) directory, use [redocly bundle](https://redocly.com/docs/cli/commands/bundle/). For example:
+To generate the bundled files in the [`docs/spec/openapi`](/docs/spec/openapi) directory, use the following make commands:
 
 ```
-npx @redocly/cli bundle apm-openapi.yaml --output bundled.yaml --ext yaml
-npx @redocly/cli bundle apm-openapi.yaml --output bundled.json --ext json
+make api-docs
+make api-docs-lint
 ```
 

docs/spec/openapi/.spectral.yaml

@@ -0,0 +1,104 @@
+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: false
+  operation-operationId-unique: false
+  operation-operationId-valid-in-url: false
+  operation-tag-defined: warn
+  operation-tags: warn
+  # Responses
+  operation-success-response: warn
+  # Schema
+  oas3-schema: error
+  oas2-schema: error
+  array-items: false
+  # 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[*].[get,put,post,delete,options,head,patch,trace]
+    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
+

docs/spec/openapi/apm-openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
-  title: APM Server
-  description: OpenAPI schema for APM Server APIs
+  title: Observability Intake APIs
+  description: OpenAPI schema for Observability Intake APIs
   version: '0.1'
   license:
     name: Elastic License 2.0

docs/spec/openapi/bundled.json

@@ -1,8 +1,8 @@
 {
   "openapi": "3.1.0",
   "info": {
-    "title": "APM Server",
-    "description": "OpenAPI schema for APM Server APIs",
+    "title": "Observability Intake APIs",
+    "description": "OpenAPI schema for Observability Intake APIs",
     "version": "0.1",
     "license": {
       "name": "Elastic License 2.0",