Skip to main content

LAB-API-102 — Swagger / OpenAPI Contract Review

LevelIntermediate
Duration75 minutes
EnvironmentBrowser / YAML editor
EvidenceAttack-surface register

Purpose​

Swagger is a widely used tooling family. The underlying interface-description standard is the OpenAPI Specification (OAS). OpenAPI descriptions can expose paths, operations, parameters, request bodies, responses, schemas and security schemes in a machine-readable form.

The latest published OAS line includes 3.2.0, while this lab fixture uses OpenAPI 3.1.2 to exercise broadly supported tooling and JSON Schema-aligned schemas.

Scenario and fixture​

Review Northstar's synthetic learner-management contract:

Task 1 — Inventory the surface​

Create one row per operation:

Operation IDMethodPathAuthenticationInputsSuccess responseError responses

Then identify:

  • path parameters and query parameters;
  • request-body media types;
  • reusable schemas under components;
  • pagination controls;
  • operations that override global security requirements.

Task 2 — Trace security schemes​

For every entry under components.securitySchemes, record:

  1. the scheme type;
  2. where the credential is carried;
  3. the scopes or claims implied by each operation;
  4. whether the description is sufficient to implement and test authentication;
  5. which authorisation decisions remain outside the OpenAPI document.

Checkpoint: A documented OAuth scope does not prove object-level authorisation. Add a separate test for cross-tenant or cross-learner resource access.

Task 3 — Review schemas as test generators​

For LearnerCreate and Learner:

  • list required fields;
  • note formats, lengths, patterns and enumerations;
  • identify read-only versus write-only properties;
  • create one valid case and two invalid boundary cases per constrained property;
  • identify personal data that should not be returned to every role.

Task 4 — Find contract defects​

Open invalid-openapi.yaml. Locate at least six defects, including:

  • a missing path-parameter declaration;
  • an undocumented success response;
  • an ambiguous security requirement;
  • an unconstrained request property;
  • inconsistent schema naming;
  • a response that may reveal sensitive data.

For each defect, state whether it is a specification validity, testability, security or maintainability issue.

Task 5 — Build a prioritised test plan​

Create at least ten tests covering:

  • authentication and token handling;
  • function-level and object-level authorisation;
  • path/query parameter validation;
  • request-body validation and mass assignment;
  • pagination and resource consumption;
  • content negotiation;
  • response schema and sensitive-data minimisation;
  • error consistency and correlation IDs;
  • idempotency for state-changing operations;
  • undocumented or deprecated operations.

Use this format:

PriorityOperationHypothesisRequest variationExpected controlEvidence

Deliverables​

  • completed operation inventory;
  • security-scheme trace;
  • defect register for the invalid fixture;
  • ten-test plan ranked by business impact and likelihood;
  • short note on tool compatibility between OAS versions.

Knowledge check​

1. Is every OpenAPI-described API necessarily RESTful?

No. OAS describes HTTP APIs and can represent many styles. The specification does not require a particular development process or strict REST architectural conformance.

2. What does an empty or missing security array prove?

It does not, by itself, prove that the API has no external security arrangements. The assessor must verify runtime controls and deployment context.

3. Why is operationId useful?

It gives a stable operation identifier for documentation, code generation, test cases and traceability, although uniqueness and naming quality still need validation.

References​