All files / src/plugins/validation/oas3/semantic-validators pagination-ibm.js

98.33% Statements 59/60
95.83% Branches 69/72
100% Functions 7/7
98.33% Lines 59/60

Press n or j to go to the next uncovered block, b, p or k for the previous block.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222                                    29x 29x   29x 74x   74x     74x         74x   122x     122x 76x       46x 45x     46x 46x     46x         17x     29x     29x   33x     6x       23x 23x   22x   1x             22x 22x   22x 22x             4x                   22x 36x   22x 12x 12x         2x                     22x 22x   36x   22x 2x 2x         2x                     22x                       22x 22x 1x           21x         2x                   22x 12x 12x 1x           11x         2x                     22x 22x 22x 3x                 74x    
// This validator checks "list" type operations for correct pagaination style.
//
// An operation is considered to be a "list" operation if:
// - its path does not end in a path parameter
// - it is a "get"
// - it contains an array at the top level of the response body object
//
// A "list" operation is considered to be a "paginated list" operation if:
// - it has a `limit` query parameter
//
// The following checks are performed on "paginated list" operations:
// - The `limit` query parameter be type integer, optional, and have default and maximum values.
// - If the operation has an `offset` query parameter, it must be type integer and optional
// - If the operation has a `start`, `cursor`, or `page_token` query parameter, it must be type string and optional
// - The response body must contain a `limit` property that is type integer and required
// - If the operation has an `offset` query parameter, the response body must contain an `offset` property this is type integer and required
// - The response body must contain an array property with the same plural resource name appearing in the collection’s URL.
 
const MessageCarrier = require('../../../utils/messageCarrier');
const mergeAllOfSchemaProperties = require('../../../utils/mergeAllOfSchemaProperties');
 
module.exports.validate = function({ resolvedSpec }, config) {
  const messages = new MessageCarrier();
 
  const checkStatus = config.pagination.pagination_style;
 
  //when pagnation is turned off, skip all of the pagination checks
  Iif (checkStatus == 'off') {
    return messages;
  }
 
  // Loop through all paths looking for "list" operations.
  for (const path in resolvedSpec.paths) {
    // For now, just consider the get operation.
    const operation = resolvedSpec.paths[path].get;
 
    // Skip any path that ends in a path parameter or does not have a "get" operation
    if (/}$/.test(path) || !operation) {
      continue;
    }
 
    // Find first success response code
    const resp = Object.keys(operation.responses || {}).find(code =>
      code.startsWith('2')
    );
    // Now get the json content of that response
    const content = resp && operation.responses[resp].content;
    const jsonResponse = content && content['application/json'];
 
    // Can't check response schema for array property, so skip this path
    if (
      !jsonResponse ||
      !jsonResponse.schema ||
      !jsonResponse.schema.properties
    ) {
      continue;
    }
 
    const jsonResponseSchema = mergeAllOfSchemaProperties(jsonResponse.schema);
 
    // If no array at top level of response, skip this path
    if (
      !Object.values(jsonResponseSchema.properties).some(
        prop => prop.type === 'array'
      )
    ) {
      continue;
    }
 
    // Check for "limit" query param -- if none, skip this path
    const params = operation.parameters;
    if (
      !params ||
      !params.some(param => param.name === 'limit' && param.in === 'query')
    ) {
      continue;
    }
 
    // Now we know we have a "paginated list" operation, so lets perform our checks
 
    // - The `limit` query parameter be type integer, optional, and have default and maximum values.
 
    const limitParamIndex = params.findIndex(
      param => param.name === 'limit' && param.in === 'query'
    );
    const limitParam = params[limitParamIndex];
    if (
      !limitParam.schema ||
      limitParam.schema.type !== 'integer' ||
      !!limitParam.required ||
      !limitParam.schema.default ||
      !limitParam.schema.maximum
    ) {
      messages.addMessage(
        ['paths', path, 'get', 'parameters', limitParamIndex],
        'The limit parameter must be of type integer and optional with default and maximum values.',
        checkStatus,
        'pagination_style'
      );
    }
 
    // - If the operation has an `offset` query parameter, it must be type integer and optional
 
    const offsetParamIndex = params.findIndex(
      param => param.name === 'offset' && param.in === 'query'
    );
    if (offsetParamIndex !== -1) {
      const offsetParam = params[offsetParamIndex];
      if (
        !offsetParam.schema ||
        offsetParam.schema.type !== 'integer' ||
        !!offsetParam.required
      ) {
        messages.addMessage(
          ['paths', path, 'get', 'parameters', offsetParamIndex],
          'The offset parameter must be of type integer and optional.',
          checkStatus,
          'pagination_style'
        );
      }
    }
 
    // - if the operation has a `start`, `cursor`, or `page_token` query parameter, it must be type string and optional
 
    const startParamNames = ['start', 'cursor', 'page_token'];
    const startParamIndex = params.findIndex(
      param =>
        param.in === 'query' && startParamNames.indexOf(param.name) !== -1
    );
    if (startParamIndex !== -1) {
      const startParam = params[startParamIndex];
      Eif (
        !startParam.schema ||
        startParam.schema.type !== 'string' ||
        !!startParam.required
      ) {
        messages.addMessage(
          ['paths', path, 'get', 'parameters', startParamIndex],
          `The ${startParam.name} parameter must be of type string and optional.`,
          checkStatus,
          'pagination_style'
        );
      }
    }
 
    // - The response body must contain a `limit` property that is type integer and required
 
    const propertiesPath = [
      'paths',
      path,
      'get',
      'responses',
      resp,
      'content',
      'application/json',
      'schema',
      'properties'
    ];
 
    const limitProp = jsonResponseSchema.properties.limit;
    if (!limitProp) {
      messages.addMessage(
        propertiesPath,
        `A paginated list operation must include a "limit" property in the response body schema.`,
        checkStatus,
        'pagination_style'
      );
    } else if (
      limitProp.type !== 'integer' ||
      !jsonResponseSchema.required ||
      jsonResponseSchema.required.indexOf('limit') === -1
    ) {
      messages.addMessage(
        [...propertiesPath, 'limit'],
        `The "limit" property in the response body of a paginated list operation must be of type integer and required.`,
        checkStatus,
        'pagination_style'
      );
    }
 
    // - If the operation has an `offset` query parameter, the response body must contain an `offset` property this is type integer and required
 
    if (offsetParamIndex !== -1) {
      const offsetProp = jsonResponseSchema.properties.offset;
      if (!offsetProp) {
        messages.addMessage(
          propertiesPath,
          `A paginated list operation with an "offset" parameter must include an "offset" property in the response body schema.`,
          checkStatus,
          'pagination_style'
        );
      } else if (
        offsetProp.type !== 'integer' ||
        !jsonResponseSchema.required ||
        jsonResponseSchema.required.indexOf('offset') === -1
      ) {
        messages.addMessage(
          [...propertiesPath, 'offset'],
          `The "offset" property in the response body of a paginated list operation must be of type integer and required.`,
          checkStatus,
          'pagination_style'
        );
      }
    }
 
    // - The response body must contain an array property with the same plural resource name appearing in the collection’s URL.
 
    const pluralResourceName = path.split('/').pop();
    const resourcesProp = jsonResponseSchema.properties[pluralResourceName];
    if (!resourcesProp || resourcesProp.type !== 'array') {
      messages.addMessage(
        propertiesPath,
        `A paginated list operation must include an array property whose name matches the final segment of the path.`,
        checkStatus,
        'pagination_style'
      );
    }
  }
 
  return messages;
};