wework
Feature: A ruleset for Microsoft Api Guidelines
Detailed description
The Microsoft Api Guidelines are used by thousands, including companies/individuals external to Microsoft. It would be extremely helpful if there were a ruleset which enforced the guidelines, and support added for scenarios which may not be lintable today with speccy's capabilities.
Context
This could be used as a baseline for standardizing api design around the world, and teaching people a form of good design without them having to read the behemoth of a document with all the guidelines. Minimally, it could save thousands of hours of time spent making pull request comments for things which a linter could do faster.
PayPal https://github.com/paypal/api-standards/blob/master/api-style-guide.md
Hey @DavidParks8!
Great suggestion. There are loooooads of these style books out there: http://apistylebook.com/
I do not think that Speccy itself should supply an implementation of the Microsoft API guidelines, but this is exactly what the rulesets are meant to enable. I want folks to be able to reference microsoft guidelines, or PayPal guidelines, or or or or from a common marketplace, which might for now just be some links on speccy.io.
It would be an interesting exercise to see how many rules you can implement as speccy/oas-kit currently is, how many would need new rule actions, and how many are utterly impossible.
This would be a fantastic experiment to see how mature the speccy/oas-kit engine is.
The npm natural module might be a good plugin for testing whether resource names are plural nouns etc.
Just to show how far I am currently implementing a ruleset for our guidelines, which are roughly based on Zalando's API guidelines. It depends on some PRs that have to be merged, but for basic validation I came quite far. Next steps is to work on rules that require to be a bit more smart.
rules:
- name: parameter-description
object: parameter
description: parameter objects should have a description
truthy: description
- name: parameter-name-regex
object: parameter
disabled: false
description: parameter names should match RFC6570
pattern:
property: name
value: ''
- name: operation-operationId
object: operation
description: operation should have an operationId
truthy: operationId
- name: operation-summary-or-description
object: operation
description: operation should have summary or description
or:
- summary
- description
- name: path-keys-no-trailing-slash
object: paths
description: paths should not end with a slash
notEndWith:
property: "$key"
value: "/"
- name: server-trailing-slash
object: server
description: server url should not have a trailing slash
notEndWith:
property: url
value: "/"
- name: reference-no-other-properties
object: reference
description: reference objects should only have a $ref property
truthy: "$ref"
properties: 1
- name: pathItem-summary-or-description
object: pathItem
disabled: true
description: pathItem should have summary or description
or:
- summary
- description
- name: example-value-or-externalValue
object: example
description: example should have either value or externalValue
xor:
- value
- externalValue
- name: reference-components-regex
object: reference
disabled: false
description: reference components should all match regex ^[a-zA-Z0-9\.\-_]+
pattern:
property: "$ref"
omit: "#"
split: "/"
value: "^[a-zA-Z0-9\\.\\-_]+$"
- name: no-script-tags-in-markdown
object: "*"
description: markdown descriptions should not contain <script> tags
notContain:
properties:
- description
value: "<script"
- name: license-apimatic-bug
object: license
description: license url should not point at gruntjs
notContain:
properties:
- url
value: gruntjs
- name: no-eval-in-descriptions
object: "*"
description: markdown descriptions should not contain 'eval('
notContain:
properties:
- description
- title
value: eval(
- name: info-contact
object: info
description: info object should contain contact object
truthy: contact
- name: contact-fields
object: contact
description: contact object needs to contain email and name
truthy:
- email
- name
- name: security-scheme
disabled: true
object: components
description: must define a security scheme
truthy: securitySchemes
- name: security-scheme-oauth2
disabled: true
object: securityScheme
description: must define a security scheme
pattern:
property: "type"
value: "oauth2"
- name: path-segments-lowercased-hyphens
object: paths
description: path items must be lowercase and separated with hyphens
pattern:
property: "$key"
split: "/"
value: "^{[^}]*}$|^([a-z-\/]*)$"
- name: disallow-uri-versioning-in-paths
object: pathItem
description: paths shouldn't contain version numbers
pattern:
property: "$key"
split: "/"
value: "^((?!v[0-9]).)*$"
- name: disallow-uri-versioning-in-server-urls
object: server
description: server url shouldn't contain version numbers
pattern:
property: "url"
split: "/"
value: "^((?!v[0-9]).)*$"
- name: path-query-parameters-snake-case
object: paths
description: path & query parameters must be in snake_case
pattern:
property: "$key"
split: "/"
value: "^(?:{[a-z_]*})$|^([a-z-])*$"
- name: parameter-name-snake-case
object: parameter
description: parameter must be in snake_case
pattern:
property: "$name"
value: "^([a-z_])*$"
- name: schema-property-name-snake-case
object: schema
description: parameter must be in snake_case
pattern:
property: "$key"
omit: "properties/"
value: "^([a-z_])*$"
- name: response-must-be-integer
object: response
description: response must be an valid HTTP status code
pattern:
property: "$key"
value: "^([0-9])*$"
- name: disallow-custom-media-types
object: content
description: don't add custom media types
pattern:
property: "$key"
value: "^(?!x-)\\w+"
- name: headers-must-be-pascal-cased
object: header
description: header must be in the form of Pascal-Case, separated by hyphens
pattern:
property: "$key"
value: "^[A-Z][a-z-](?:[A-Z][a-z-]*)*$"
I was just going to ask if you could add some of these new rules to the oas-kit wiki... and I see you have! Can't wait to see what you can come up with using the new schema rule!
Can we generate a report: Let say we are having a spec and we are passing the mentioned rule set, then output must contain detailed description of what rules it passed as well the the rules that got failed.
