Skip to content

Commit edb2785

Browse files
lcawllcawl
authored
[DOCS] Add api-docs to makefile; add linting rules (#13664)
* Add api-docs to makefile; add linting rules * Turn off misleading array-errors linting rule
1 parent 1bbb9d2 commit edb2785

File tree

5 files changed

+121
-7
lines changed

5 files changed

+121
-7
lines changed

‎Makefile

+10
Original file line numberDiff line numberDiff line change
@@ -326,3 +326,13 @@ smoketest/all/cleanup:
326326
echo "-> Cleanup $${test_dir} smoke tests..."; \
327327
$(MAKE) smoketest/cleanup TEST_DIR=$${test_dir}; \
328328
done
329+
330+
.PHONY: api-docs
331+
api-docs: ## Generate bundled OpenAPI documents
332+
@npx @redocly/cli bundle "docs/spec/openapi/apm-openapi.yaml" --ext yaml --output "docs/spec/openapi/bundled.yaml"
333+
@npx @redocly/cli bundle "docs/spec/openapi/apm-openapi.yaml" --ext json --output "docs/spec/openapi/bundled.json"
334+
335+
.PHONY: api-docs-lint
336+
api-docs-lint: ## Run spectral API docs linter
337+
@npx @stoplight/spectral-cli lint "docs/spec/openapi/bundled.yaml" --ruleset "docs/spec/openapi/.spectral.yaml"
338+

‎docs/README.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,10 @@
99
> * **Sample data sets** that are injected into the docs are in the [`docs/data/`](/docs/data/) directory.
1010
> * **Specifications** that are injected into the docs are in the [`docs/spec/`](/docs/spec/) directory.
1111
12-
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:
12+
To generate the bundled files in the [`docs/spec/openapi`](/docs/spec/openapi) directory, use the following make commands:
1313

1414
```
15-
npx @redocly/cli bundle apm-openapi.yaml --output bundled.yaml --ext yaml
16-
npx @redocly/cli bundle apm-openapi.yaml --output bundled.json --ext json
15+
make api-docs
16+
make api-docs-lint
1717
```
1818

‎docs/spec/openapi/.spectral.yaml

+104
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
extends: ["spectral:oas"]
2+
rules:
3+
# Built-in rules
4+
# Descriptions
5+
oas3-parameter-description: warn
6+
oas2-parameter-description: warn
7+
tag-description: info
8+
# Document info
9+
info-contact: info
10+
info-description: warn
11+
info-license: warn
12+
# Examples
13+
oas3-valid-media-example: false
14+
oas3-valid-schema-example: false
15+
oas2-valid-media-example: false
16+
# Operations
17+
operation-operationId: false
18+
operation-operationId-unique: false
19+
operation-operationId-valid-in-url: false
20+
operation-tag-defined: warn
21+
operation-tags: warn
22+
# Responses
23+
operation-success-response: warn
24+
# Schema
25+
oas3-schema: error
26+
oas2-schema: error
27+
array-items: false
28+
# Tags
29+
openapi-tags: warn
30+
openapi-tags-alphabetical: info
31+
# Turn off some built-in rules
32+
operation-description: false
33+
operation-singular-tag: false
34+
# Custom rules
35+
# Descriptions
36+
avoid-problematic-words:
37+
description: Ban certain words from descriptions
38+
message: "Use appropriate replacements for problematic terms"
39+
severity: warn
40+
given: "$..*.description"
41+
then:
42+
function: pattern
43+
functionOptions:
44+
notMatch: /(blacklist|whitelist|execute|kill)/i
45+
# Examples
46+
operation-success-examples:
47+
formats: ["oas3_1"]
48+
description: Response code 200 should have at least one example.
49+
message: "Each response body should have a realistic example. It must not contain any sensitive or confidential data."
50+
severity: info
51+
given: $.paths[*].[*].responses.[200].content.[application/json]
52+
then:
53+
field: examples
54+
function: defined
55+
# Extensions
56+
internal-extension:
57+
description: Operations should not have x-internal extension.
58+
message: "Do not publish x-internal operations"
59+
severity: error
60+
given: $.paths[*].[get,put,post,delete,options,head,patch,trace]
61+
then:
62+
field: x-internal
63+
function: undefined
64+
# Operations
65+
operation-summary:
66+
description: Operations should have summaries.
67+
message: "Each operation should have a summary"
68+
severity: error
69+
recommended: true
70+
given: $.paths[*].[get,put,post,delete,options,head,patch,trace]
71+
then:
72+
field: summary
73+
function: defined
74+
operation-summary-length:
75+
description: Operation summary should be between 5 and 45 characters
76+
given: "$.paths[*].[get,put,post,delete,options,head,patch,trace]"
77+
then:
78+
field: summary
79+
function: length
80+
functionOptions:
81+
max: 45
82+
min: 5
83+
severity: warn
84+
simple-verbs-in-summary:
85+
given:
86+
- "$.paths[*][*].summary"
87+
then:
88+
function: pattern
89+
functionOptions:
90+
notMatch: "Retrieve|Return|List *"
91+
severity: warn
92+
description: Summaries should use common verbs.
93+
message: "Summaries should use common verbs like Get, Update, Delete whenever possible"
94+
# NOTE: This one hiccups on acronyms so perhaps too noisy
95+
# docs-operation-summary-sentence-case:
96+
# description: Operation summary should be sentence cased
97+
# given: "$.paths[*].[get,put,post,delete,options,head,patch,trace]"
98+
# then:
99+
# field: summary
100+
# function: pattern
101+
# functionOptions:
102+
# match: /^[A-Z]+[^A-Z]+$/
103+
# severity: warn
104+

‎docs/spec/openapi/apm-openapi.yaml

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
openapi: 3.1.0
22
info:
3-
title: APM Server
4-
description: OpenAPI schema for APM Server APIs
3+
title: Observability Intake APIs
4+
description: OpenAPI schema for Observability Intake APIs
55
version: '0.1'
66
license:
77
name: Elastic License 2.0

‎docs/spec/openapi/bundled.json

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
{
22
"openapi": "3.1.0",
33
"info": {
4-
"title": "APM Server",
5-
"description": "OpenAPI schema for APM Server APIs",
4+
"title": "Observability Intake APIs",
5+
"description": "OpenAPI schema for Observability Intake APIs",
66
"version": "0.1",
77
"license": {
88
"name": "Elastic License 2.0",

0 commit comments

Comments
 (0)