Skip to content

Commit

Permalink
Merge remote-tracking branch 'origin/develop' into fix/core/bump-nimma
Browse files Browse the repository at this point in the history
  • Loading branch information
P0lip committed Jun 24, 2022
2 parents a559cd4 + f0aecda commit 815e1ed
Show file tree
Hide file tree
Showing 12 changed files with 562 additions and 66 deletions.
4 changes: 2 additions & 2 deletions docs/getting-started/1-concepts.md
Expand Up @@ -4,11 +4,11 @@ The power of integrating linting into the design-first workflow, or any workflow

To achieve this, Spectral has three key concepts:

- **Rulesets** act as a container for rules and functions.
- **Rules** filter your object down to a set of target values and specify the function that is used to evaluate those values.
- **Functions** accept a value and return issues if the value is incorrect.
- **Rulesets** act as a container for rules and functions.

Rules can be comprised of one of more functions. For example:
Rules can be comprised of one of more functions, to standardize structured content, like making sure your OpenAPI descriptions match your [API style guides](https://stoplight.io/api-style-guides-guidelines-and-best-practices):

- HTTP Basic is not allowed at this company
- All operations are secured with a security schema
Expand Down
4 changes: 2 additions & 2 deletions docs/getting-started/3-rulesets.md
Expand Up @@ -83,8 +83,8 @@ Formats are an optional way to specify which API description formats a rule, or
- `aas2_4` (AsyncAPI v2.4.0)
- `oas2` (OpenAPI v2.0)
- `oas3` (OpenAPI v3.x)
- `oas3.0` (OpenAPI v3.0.x)
- `oas3.1` (OpenAPI v3.1.x)
- `oas3_0` (OpenAPI v3.0.x)
- `oas3_1` (OpenAPI v3.1.x)
- `json-schema` (`$schema` says this is some JSON Schema draft)
- `json-schema-loose` (looks like JSON Schema, but no `$schema` found)
- `json-schema-draft4` (`$schema` says this is JSON Schema Draft 04)
Expand Down
45 changes: 45 additions & 0 deletions docs/reference/asyncapi-rules.md
Expand Up @@ -132,6 +132,51 @@ info:
name: MIT
```

### asyncapi-message-examples

All `examples` in message object should follow by `payload` and `headers` schemas.

**Bad Example**

```yaml
asyncapi: "2.0.0"
info:
title: Bad API
version: "1.0.0"
components:
messages:
someMessage:
payload:
type: string
headers:
type: object
examples:
- payload: 2137
headers: someHeader
```

**Good Example**

```yaml
asyncapi: "2.0.0"
info:
title: Good API
version: "1.0.0"
components:
messages:
someMessage:
payload:
type: string
headers:
type: object
examples:
- payload: foobar
headers:
someHeader: someValue
```

**Recommended:** Yes

### asyncapi-operation-description

Operation objects should have a description.
Expand Down
37 changes: 16 additions & 21 deletions docs/reference/openapi-rules.md
Expand Up @@ -6,7 +6,7 @@ In your ruleset file you can add `extends: "spectral:oas"` and you'll get all of

## OpenAPI v2 & v3

These rules apply to both OpenAPI v2 and v3.
These rules apply to both OpenAPI v2.0, v3.0, and most likely v3.1, although there are some differences.

### operation-success-response

Expand Down Expand Up @@ -186,7 +186,7 @@ info:

### no-\$ref-siblings

An object exposing a `$ref` property cannot be further extended with additional properties.
Prior to OpenAPI v3.1, keywords next to `$ref` were be ignored by most tooling, but not all. This leads to inconsistent experiences depending on what combinations of tools are used. As of v3.1 $ref siblings are allowed, so this rule will not be applied.

**Recommended:** Yes

Expand All @@ -195,9 +195,8 @@ An object exposing a `$ref` property cannot be further extended with additional
```yaml
TheBadModel:
$ref: "#/components/TheBadModelProperties"
examples: # <= This property will be ignored
an_example:
name: something
# This property should be ignored
example: May or may not show up
```

### no-eval-in-markdown
Expand Down Expand Up @@ -502,15 +501,13 @@ Ignores empty `security` values for cases where authentication is explicitly not

Potential unused reusable `definition` entry has been detected.

_Warning:_ This rule may identify false positives when linting a specification
that acts as a library (a container storing reusable objects, leveraged by other
specifications that reference those objects).
<!-- theme: warning -->

**Recommended:** Yes

### oas2-valid-example

Examples must be valid against their defined schema.
> #### Warning
>
> This rule may identify false positives when linting a specification
> that acts as a library (a container storing reusable objects, leveraged by other
> specifications that reference those objects).
**Recommended:** Yes

Expand Down Expand Up @@ -640,15 +637,13 @@ servers:

Potential unused reusable `components` entry has been detected.

_Warning:_ This rule may identify false positives when linting a specification
that acts as a library (a container storing reusable objects, leveraged by other
specifications that reference those objects).

**Recommended:** Yes

### oas3-valid-example
<!-- theme: warning -->

Examples must be valid against their defined schema.
> #### Warning
>
> This rule may identify false positives when linting a specification
> that acts as a library (a container storing reusable objects, leveraged by other
> specifications that reference those objects).
**Recommended:** Yes

Expand Down
6 changes: 3 additions & 3 deletions packages/core/package.json
Expand Up @@ -44,16 +44,16 @@
"@stoplight/spectral-parsers": "^1.0.0",
"@stoplight/spectral-ref-resolver": "^1.0.0",
"@stoplight/spectral-runtime": "^1.0.0",
"@stoplight/types": "13.1.0",
"@types/json-schema": "^7.0.7",
"@stoplight/types": "~13.2.0",
"@types/json-schema": "^7.0.11",
"ajv": "^8.6.0",
"ajv-errors": "~3.0.0",
"ajv-formats": "~2.1.0",
"blueimp-md5": "2.18.0",
"jsonpath-plus": "6.0.1",
"lodash": "~4.17.21",
"lodash.topath": "^4.5.2",
"minimatch": "3.0.4",
"minimatch": "3.1.2",
"nimma": "0.2.2",
"pony-cause": "^1.0.0",
"simple-eval": "1.0.0",
Expand Down
7 changes: 7 additions & 0 deletions packages/rulesets/CHANGELOG.md
@@ -1,3 +1,10 @@
# [@stoplight/spectral-rulesets-v1.10.0](https://github.com/stoplightio/spectral/compare/@stoplight/spectral-rulesets-v1.9.0...@stoplight/spectral-rulesets-v1.10.0) (2022-06-07)


### Features

* **rulesets:** add rule to validate AsyncAPI message's examples ([#2126](https://github.com/stoplightio/spectral/issues/2126)) ([87ef046](https://github.com/stoplightio/spectral/commit/87ef0464c1d31a8887c847e339a4b1bef3e5ad93))

# [@stoplight/spectral-rulesets-v1.9.0](https://github.com/stoplightio/spectral/compare/@stoplight/spectral-rulesets-v1.8.0...@stoplight/spectral-rulesets-v1.9.0) (2022-05-31)


Expand Down
2 changes: 1 addition & 1 deletion packages/rulesets/package.json
@@ -1,6 +1,6 @@
{
"name": "@stoplight/spectral-rulesets",
"version": "1.9.0",
"version": "1.10.0",
"homepage": "https://github.com/stoplightio/spectral",
"bugs": "https://github.com/stoplightio/spectral/issues",
"author": "Stoplight <support@stoplight.io>",
Expand Down
@@ -0,0 +1,197 @@
import { DiagnosticSeverity } from '@stoplight/types';
import testRule from './__helpers__/tester';

testRule('asyncapi-message-examples', [
{
name: 'valid case',
document: {
asyncapi: '2.0.0',
channels: {
someChannel: {
publish: {
message: {
payload: {
type: 'string',
},
headers: {
type: 'object',
},
examples: [
{
payload: 'foobar',
headers: {
someKey: 'someValue',
},
},
],
},
},
},
},
},
errors: [],
},

{
name: 'invalid case',
document: {
asyncapi: '2.0.0',
channels: {
someChannel: {
publish: {
message: {
payload: {
type: 'string',
},
headers: {
type: 'object',
},
examples: [
{
payload: 2137,
headers: {
someKey: 'someValue',
},
},
],
},
},
},
},
},
errors: [
{
message: '"payload" property type must be string',
path: ['channels', 'someChannel', 'publish', 'message', 'examples', '0', 'payload'],
severity: DiagnosticSeverity.Error,
},
],
},

{
name: 'invalid case (oneOf case)',
document: {
asyncapi: '2.0.0',
channels: {
someChannel: {
publish: {
message: {
oneOf: [
{
payload: {
type: 'string',
},
headers: {
type: 'object',
},
examples: [
{
payload: 2137,
headers: {
someKey: 'someValue',
},
},
],
},
],
},
},
},
},
},
errors: [
{
message: '"payload" property type must be string',
path: ['channels', 'someChannel', 'publish', 'message', 'oneOf', '0', 'examples', '0', 'payload'],
severity: DiagnosticSeverity.Error,
},
],
},

{
name: 'invalid case (inside components.messages)',
document: {
asyncapi: '2.0.0',
components: {
messages: {
someMessage: {
payload: {
type: 'string',
},
headers: {
type: 'object',
},
examples: [
{
payload: 2137,
headers: {
someKey: 'someValue',
},
},
],
},
},
},
},
errors: [
{
message: '"payload" property type must be string',
path: ['components', 'messages', 'someMessage', 'examples', '0', 'payload'],
severity: DiagnosticSeverity.Error,
},
],
},

{
name: 'invalid case (with multiple errors)',
document: {
asyncapi: '2.0.0',
components: {
messages: {
someMessage: {
payload: {
type: 'object',
required: ['key1', 'key2'],
properties: {
key1: {
type: 'string',
},
key2: {
type: 'string',
},
},
},
headers: {
type: 'object',
},
examples: [
{
payload: {
key1: 2137,
},
headers: 'someValue',
},
],
},
},
},
},
errors: [
{
message: '"payload" property must have required property "key2"',
path: ['components', 'messages', 'someMessage', 'examples', '0', 'payload'],
severity: DiagnosticSeverity.Error,
},
{
message: '"key1" property type must be string',
path: ['components', 'messages', 'someMessage', 'examples', '0', 'payload', 'key1'],
severity: DiagnosticSeverity.Error,
},
{
message: '"headers" property type must be object',
path: ['components', 'messages', 'someMessage', 'examples', '0', 'headers'],
severity: DiagnosticSeverity.Error,
},
],
},
]);

0 comments on commit 815e1ed

Please sign in to comment.