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