Skip to content

Latest commit

 

History

History
114 lines (69 loc) · 8.29 KB

doc-completeness.md

File metadata and controls

114 lines (69 loc) · 8.29 KB

Documentation Completeness Ruleset

The Documentation Completeness Ruleset consists of 2 domains:

  • API definition completeness (paths, schemas, response status and error codes):
    • Must be a well-formed JSON or YAML document
    • Must have an OAS version
    • Must be a well-formed OpenAPI document
    • Must contain meta information about the API itself
    • Must contain a schema definition
    • Must have response schema defined
    • Must have success status code definitions
    • Must have error status code definitions
  • Reference documentation completeness (descriptions, examples):
    • Must have descriptions for every attribute
    • Must have examples for every schema

Rules

name_id description severity mitigation
oas[2/3]-schema Malformed OAS document, not adhering to the OpenAPI v2/v3 specifications. error Please fix the items identified to adhere to the OpenAPI v2/v3 specifications. Reference
oas-version The version of OpenAPI is not specified. error Please add the OpenAPI attributes identified as missing and provide values for these attributes. Reference
info-contact Info object must have contact object. warning Please add missing contact object. Reference
info-description Info object must have a non-empty description. warning Please add missing description. Reference
info-license Info object must have license object. warning Please add missing license object. Reference
license-url License object must have a url. warning Please add missing url. Reference
oas[2/3]-missing-schema-definition Some schema definitions are missing. error Please add schema definitions for the items detected. Reference
general-schema-definition Some schemas are partially defined. error Please fully describe the schema for the items detected as using object. Reference
oas[2/3]-missing-returned-representation Some responses do not define a schema. error Please add a schema for the items detected. Reference
success-status-code Some operations do not define a success status code. error Please add a success status code in the 1xx, 2xx or 3xx range for the items identified. Reference
error-status-code Some operations do not define errors. warning Please add an error status code for the items identified. Reference
description-for-every-attribute Some attributes do not provide a description. warning Please add a description for the items identified. Reference
examples-for-every-schema Examples are not provided for some of the schemas. warning Please add examples for the schemas identified. Reference

API Definition Completeness

Check the completeness of an OAS document.

Well-formed JSON or YAML document

  • The document must be syntactically correct regarding the JSON or YAML syntax, parser should not complain

oas-version: Version of the OAS is missing

  • The document must specify the OAS version it is supporting.

oas[2|3]-schema: Well-formed OpenAPI document

  • The document must be syntactically correct regarding the version of OAS it declares

Meta Information about the API itself

The following fields must be present (note: list of fields depend on the OAS version) List for OAS v2:

  • info
  • title
  • version
  • basepath
  • License
  • SecurityDefinitions

List of that are implemented for this check.

  • oas[2|3]-meta-info
  • info-contact
  • info-description
  • info-license

oas[2|3]-missing-schema-definition: Missing Schema Definition

  • There is no schema attribute for a component

general-schema-definition: Generic Schema Definition

  • Some of the defined schema use object as a final field when describing their object structure.

oas[2-3]-missing-returned-representation: Missing Returned Representation

  • 2XX (except 204) and 4xx responses must have a response schema defined.

success-status-code: Missing Success Status Code

  • For every operation in the OAS document, there should be at least one success status code defined.

  • A successful status code is in the 1xx, 2xx or 3xx range series, and generally a 200, 201 or 204. Missing response schema object properties.

error-status-code: Missing Error Status Codes

  • There should be at least one error status code either 4xx or 5xx (or default per the OpenAPI spec / search for Default Response)

  • There are no error codes, only 200 OK

Reference Documentation Completeness

description-for-every-attribute: Descriptions for Every Attribute

  • For every attribute that is present in the OAS document, if a description is proposed as optional to complement that attribute, then yes it must be present.

examples-for-every-schema: Examples for Every Schema

  • For every schema provided in the OAS document, at least one example must be present