API Evangelist enhancements for the GZW Data API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the GZW Data API
  version: 1.0.0
x-provenance:
  generated: '2026-09-03'
  method: generated
  source: openapi/_original/gzw-data-openapi.json (verbatim from https://gzw-data.dev/api/v1/spec, implementation 4.2.0, re-fetched 2026-09-03)
  note: >-
    Non-destructive Overlay 1.0.0 capturing enhancements API Evangelist derived from the provider's
    own docs and from live probes. REVISED 2026-09-03 for implementation 4.2.0: the provider has
    since added the responses this overlay previously had to describe from the outside — all 362
    operations now declare 200/400/404/429 against shared $ref schemas, and 176 declare their path
    parameters. What the contract STILL omits, and what this overlay therefore still carries, is:
    operationIds, operation descriptions, tags, contact/licence/terms metadata, an explicit empty
    security requirement, and every QUERY parameter (page, per_page, all, search, sort, field
    equality, and the four search-route parameters dataset/fields/fuzzy/limit) — zero query
    parameters are declared anywhere in 4.2.0. It does NOT invent endpoint behaviour and it does not
    modify openapi/_original/gzw-data-openapi.json.
extends: openapi/_original/gzw-data-openapi.json
actions:
- target: $.info
  description: Add contact, licence, terms and a fuller description sourced from the provider's own pages.
  update:
    description: >-
      Free, fan-made, read-only REST API for Gray Zone Warfare game data — 85+ auto-discovered
      datasets covering weapons, ammo, armor, tasks/missions, gear, loot, containers and vendors,
      scraped from the community GZW Fandom Wiki. No API key and no account required. Best-effort
      rate limit of 100 requests per minute per IP. Not affiliated with or endorsed by the game's
      publisher.
    termsOfService: https://gzw-data.dev/terms-of-service/
    contact:
      name: ZoniBoy00
      url: https://github.com/ZoniBoy00/gzw-data/issues
    license:
      name: MIT
      url: https://github.com/ZoniBoy00/gzw-data/blob/main/LICENSE
    x-privacy-policy: https://gzw-data.dev/privacy-policy/
    x-data-source: https://gray-zone-warfare.fandom.com/wiki/Gray_Zone_Warfare_Wiki
- target: $
  description: Declare an explicitly empty security requirement — the API is public and unauthenticated.
  update:
    security: []
    x-authentication: none
    x-api-key-required: false
- target: $.servers
  description: Note the legacy compatibility prefix alongside the versioned base.
  update:
  - url: https://gzw-data.dev
    description: Production. Use the /api/v1 prefix for new integrations; the unversioned /api prefix is compatibility-only.
- target: $.info
  description: Record the runtime conventions the docs publish but the contract omits.
  update:
    x-rate-limit:
      limit: 100
      window: 1 minute
      scope: per-ip
      enforcement: best-effort (per warm serverless instance, not a strict global quota)
      headers: [X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After]
      exhausted_status: 429
    x-caching:
      data_routes: 'Cache-Control: public, max-age=300'
      validators: weak ETag
    x-cors:
      allow_origin: '*'
    x-contract-version-observed:
      implementation_version: 4.2.0
      observed: '2026-09-03'
      previous: 4.0.0 observed 2026-08-26
      responses_declared: true
      query_parameters_declared: false
    x-search-parameters:
    - name: q
      description: The search query, on GET /api/v1/search.
    - name: dataset
      description: Limit the search to one or more comma-separated datasets.
    - name: fields
      description: Search only the named comma-separated fields.
    - name: fuzzy
      description: fuzzy=true allows small spelling and punctuation differences.
    - name: limit
      description: Matches per dataset; documented maximum 50.
    x-query-parameters:
    - name: page
      description: 1-based page number. Default 1.
    - name: per_page
      description: Page size. Default 50, documented cap 500.
    - name: all
      description: all=true returns every filtered record without pagination.
    - name: search
      description: Full-text search across the record fields of the dataset.
    - name: sort
      description: 'Sort by a field, syntax field:asc or field:desc.'
    - name: '{field}'
      description: Filter by equality on any string field, e.g. ?type=Keycard.
    x-response-envelope:
      fields: [data, count, page, perPage, total, totalPages, source, timestamp]
      note: Unpaginated responses omit the pagination fields and keep data, count, source, timestamp.
- target: $.components.schemas.ApiErrorResponse
  description: Document the additional envelope members observed on live error responses.
  update:
    x-observed-members:
      dataVersion: ISO timestamp of the scrape the response was served from
    x-error-codes:
    - code: ENDPOINT_NOT_FOUND
      status: 404
      note: Body carries an `available` array of the dataset names that DO exist.
    - code: RECORD_NOT_FOUND
      status: 404
      note: Body carries `dataset`, `id` and a `docs` pointer to /api/v1/spec.
    - code: DATASET_NOT_FOUND
      status: 404
    x-not-rfc9457: >-
      Served as application/json with a vendor {error:{code,message},source,timestamp} envelope;
      not application/problem+json.
- target: $.paths
  description: Record the live, documented routes that are ABSENT from the published contract.
  update:
    x-undocumented-in-spec:
      note: >-
        These routes are documented in the provider's own README, docs and llms.txt AND return 200
        live, but no path item for them exists in the published OpenAPI. NARROWED 2026-09-03:
        /api/v1/search was on this list against 4.0.0 and is now DECLARED in 4.2.0, along with the
        new /version, /changes, /schema/{dataset} and /items/{id}/context routes. Only /stats,
        /images and /spec itself remain undeclared. Listed here as a gap for the
        provider; they are deliberately NOT added as path items, because this overlay does not author
        contract that the provider has not published.
      routes:
      - GET /api/v1/stats — per-dataset item counts plus latest scrape timestamp (probed 200)
      - GET /api/v1/images — all item image URLs (probed 200)
      - GET /api/v1/spec — the OpenAPI document itself (probed 200)
      - GET /api/v1/metadata?full=true — detailed metadata for all datasets
- target: $.paths['/api/v1/weapons'].get
  description: Illustrative enrichment of one representative collection operation. Every collection route follows this shape.
  update:
    operationId: listWeapons
    tags: [weapons]
    description: >-
      List Gray Zone Warfare weapons. Supports equality filters on any string field, full-text
      search, sorting, and page-number pagination. Data is wiki-derived and refreshed by the
      weekly scraper.
    x-derived-by: API Evangelist overlay — the published operation carries only a summary.
- target: $.paths['/api/v1/weapons/{id}'].get
  description: Illustrative enrichment of one representative single-record operation.
  update:
    operationId: getWeapon
    tags: [weapons]
    description: >-
      Retrieve one weapon by its exact slugified id (e.g. ak-12). Ids are matched exactly; use the
      collection route with ?search= to resolve a display name to an id first. A missing id returns
      404 RECORD_NOT_FOUND.
    x-derived-by: API Evangelist overlay — the published operation carries only a summary.