Skip to content

Commit 8508213

Browse files
danielgtaylordanielgtaylor
committed
feat: plural resource nouns
1 parent de0e614 commit 8508213

20 files changed

+164
-17
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
node_modules
22
/.spectral.yaml
33
isp-functions/english.js
4+
isp-functions/noun.js

‎fixtures/disable/openapi.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ tags:
1313
- name: Test
1414
description: Test tag
1515
paths:
16-
/test:
16+
/tests:
1717
get:
1818
summary: Test operation
1919
description: Test operation description

‎fixtures/lint/casing-fail.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ tags:
1313
- name: Test
1414
description: Test tag
1515
paths:
16-
/test:
16+
/tests:
1717
get:
1818
summary: Test operation
1919
description: Test operation description

‎fixtures/lint/casing-pass.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ tags:
1313
- name: Test
1414
description: Test tag
1515
paths:
16-
/test:
16+
/tests:
1717
get:
1818
summary: Test operation
1919
description: Test operation description

‎fixtures/lint/date-fail.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ tags:
1313
- name: Test
1414
description: Test tag
1515
paths:
16-
/test:
16+
/tests:
1717
get:
1818
summary: Test operation
1919
description: Test operation description

‎fixtures/lint/date-pass.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ tags:
1313
- name: Test
1414
description: Test tag
1515
paths:
16-
/test:
16+
/tests:
1717
get:
1818
summary: Test operation
1919
description: Test operation description

‎fixtures/lint/english-fail.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ tags:
1414
- name: Test
1515
description: Test tag
1616
paths:
17-
/test:
17+
/tests:
1818
get:
1919
summary: Test operation
2020
description: Test operation description

‎fixtures/lint/english-pass.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ tags:
1313
- name: Test
1414
description: Test tag
1515
paths:
16-
/test:
16+
/tests:
1717
get:
1818
summary: Test operation
1919
description: Test operation description

‎fixtures/lint/json-fail.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ tags:
1313
- name: Test
1414
description: Test tag
1515
paths:
16-
/test:
16+
/tests:
1717
get:
1818
summary: Test operation
1919
description: Test operation description

‎fixtures/lint/json-pass.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ tags:
1313
- name: Test
1414
description: Test tag
1515
paths:
16-
/test:
16+
/tests:
1717
get:
1818
summary: Test operation
1919
description: Test operation description

‎fixtures/lint/noun-fail.yaml

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
openapi: '3.0.0'
2+
info:
3+
version: 1.0.0
4+
title: API Fixture
5+
description: API fixture description
6+
license:
7+
name: Apache2
8+
contact:
9+
email: [email protected]
10+
servers:
11+
- url: https://api.example.com/v1
12+
tags:
13+
- name: Test
14+
description: Test tag
15+
paths:
16+
/get_foo:
17+
get:
18+
summary: Test operation
19+
description: Test operation description
20+
operationId: test-foo
21+
tags:
22+
- Test
23+
responses:
24+
'204':
25+
description: Response description
26+
/bar:
27+
get:
28+
summary: Test operation
29+
description: Test operation description
30+
operationId: test-bar
31+
tags:
32+
- Test
33+
responses:
34+
'204':
35+
description: Response description

‎fixtures/lint/noun-pass.yaml

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
openapi: '3.0.0'
2+
info:
3+
version: 1.0.0
4+
title: API Fixture
5+
description: API fixture description
6+
license:
7+
name: Apache2
8+
contact:
9+
email: [email protected]
10+
servers:
11+
- url: https://api.example.com/v1
12+
tags:
13+
- name: Test
14+
description: Test tag
15+
paths:
16+
/foos:
17+
get:
18+
summary: Test operation
19+
description: Test operation description
20+
operationId: test-foo
21+
tags:
22+
- Test
23+
responses:
24+
'204':
25+
description: Response description
26+
/givens:
27+
get:
28+
summary: Test operation
29+
description: Test operation description
30+
operationId: test-bar
31+
tags:
32+
- Test
33+
responses:
34+
'204':
35+
description: Response description

‎fixtures/lint/patch-fail.yaml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ tags:
1313
- name: Test
1414
description: Test tag
1515
paths:
16-
/test:
16+
/tests:
1717
patch:
1818
summary: Test operation
1919
description: Test operation description
@@ -29,7 +29,7 @@ paths:
2929
responses:
3030
'204':
3131
description: Response description
32-
/warn:
32+
/warnings:
3333
patch:
3434
summary: Warn operation
3535
description: Test operation description

‎fixtures/lint/patch-pass.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ tags:
1313
- name: Test
1414
description: Test tag
1515
paths:
16-
/test:
16+
/tests:
1717
patch:
1818
summary: Test operation
1919
description: Test operation description

‎fixtures/lint/servers-fail.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ tags:
1313
- name: Test
1414
description: Test tag
1515
paths:
16-
/test:
16+
/tests:
1717
get:
1818
summary: Test operation
1919
description: Test operation description

‎fixtures/lint/servers-pass.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ tags:
1414
- name: Test
1515
description: Test tag
1616
paths:
17-
/test:
17+
/tests:
1818
get:
1919
summary: Test operation
2020
description: Test operation description

‎isp-functions/noun-deps.js

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
const inflection = require('inflection');
2+
3+
const VERBS = [
4+
'allow',
5+
'create',
6+
'make',
7+
'open',
8+
'begin',
9+
'write',
10+
'convert',
11+
'put',
12+
'set',
13+
'read',
14+
'get',
15+
'fetch',
16+
'take',
17+
'give',
18+
'find',
19+
'delete',
20+
'close'
21+
];
22+
23+
// The noun function takes the name of something and returns an error if it
24+
// appears to not be a plural noun.
25+
module.exports = targetValue => {
26+
const value = targetValue.split('/').pop();
27+
28+
if (value.startsWith('{')) {
29+
// This is a path parameter. Skip it!
30+
return;
31+
}
32+
33+
// Test each verb to see if the value matches or begins with it. The
34+
// regex below is to prevent e.g. `giver` from triggering the error
35+
// since it is a noun that begins with a verb.
36+
for (const verb of VERBS)
37+
if (
38+
(value.length === verb.length && value === verb) ||
39+
(value.length > verb.length &&
40+
value.startsWith(verb) &&
41+
value[verb.length].match(/[ -_A-Z]/))
42+
) {
43+
return [
44+
{
45+
message: `${value} should be a noun`
46+
}
47+
];
48+
}
49+
50+
// Pluralization exceptions.
51+
if (value === 'me' || value === 'search') {
52+
return;
53+
}
54+
55+
const plural = inflection.pluralize(value);
56+
if (value !== plural) {
57+
return [
58+
{
59+
message: `${value} should be plural: ${plural}`
60+
}
61+
];
62+
}
63+
};

‎isp-rules.yaml

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ functions:
66
- contains
77
- english
88
- iso8601
9+
- noun
910
rules:
1011
# English recommendations for description fields
1112
english:
@@ -55,9 +56,15 @@ rules:
5556
given: $..parameters.[*]
5657
then:
5758
function: iso8601
58-
# Auth?
59-
# Resource nouns
59+
# Auth? TODO
60+
# Resource plural nouns
61+
resource-nouns:
62+
severity: error
63+
given: $.paths.*~
64+
then:
65+
function: noun
6066
# DNS & URL friendliness
67+
6168
# Resources should have schemas with descriptions
6269
# Resource field casing
6370
# Don't POST with identifier

‎package-lock.json

Lines changed: 5 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,15 @@
55
"description": "",
66
"main": "main.js",
77
"scripts": {
8-
"build": "browserify -s english -o isp-functions/english.js isp-functions/english-deps.js",
8+
"build": "browserify -s english -o isp-functions/english.js isp-functions/english-deps.js && browserify -s noun -o isp-functions/noun.js isp-functions/noun-deps.js",
99
"test": "mocha --timeout=5000"
1010
},
1111
"author": "Daniel G. Taylor <[email protected]",
1212
"license": "Apache2",
1313
"dependencies": {
1414
"@stoplight/spectral": "^5.0.0",
1515
"browserify": "^16.5.0",
16+
"inflection": "^1.12.0",
1617
"js-yaml": "^3.13.1",
1718
"mocha": "^7.0.1",
1819
"write-good": "^1.0.2"

0 commit comments

Comments
 (0)