overlay: 1.0.0
info:
  title: API Evangelist enhancements — OwnLocal API — Categories
  version: 1.0.0
extends: ../openapi/ownlocal-categories-openapi.yml
x-generated: '2026-08-12'
x-method: generated
x-source: openapi/_original/ownlocal-swagger.json (verbatim from https://admin.austin.ownlocal.com/api-docs/v1/swagger.json)
  cross-read against https://api.docs.ownlocal.com/
x-note: 'Records what API Evangelist added on top of OwnLocal''s own contract during the Swagger 2.0 -> OpenAPI
  3.1.0 conversion. Nothing here changes OwnLocal''s described behaviour: every added value is either a restatement
  of something OwnLocal publishes in prose (the server host, the auth mechanics, support contact) or a structural
  identifier the source omitted (operationIds, tag declarations). No endpoint, parameter, field or schema is invented.
  The original is preserved byte-for-byte at openapi/_original/ownlocal-swagger.json and is never mutated.'
actions:
- target: $
  description: Add servers[]. OwnLocal's published Swagger 2.0 declares no host, basePath or schemes, so the source
    contract never names the server it describes. The host is taken verbatim from the published API reference
    at https://api.docs.ownlocal.com/, where every curl example calls https://admin.austin.ownlocal.com/api/v1/...
  update:
    servers:
    - url: https://admin.austin.ownlocal.com
      description: OwnLocal production API host (per the published API reference)
- target: $
  description: Link the machine contract back to the human reference it was cross-read against.
  update:
    externalDocs:
      description: OwnLocal API Docs
      url: https://api.docs.ownlocal.com/
- target: $.info
  description: Add contact (support@ownlocal.com / the support page, both published by OwnLocal) and a tag-scoped
    description. The source info block carries only title and version.
  update:
    description: The OwnLocal business category and sub-category vocabulary used to classify businesses and filter
      ads.
    contact:
      name: OwnLocal Support
      email: support@ownlocal.com
      url: https://www.ownlocal.com/support/
- target: $
  description: Declare the tag. The source Swagger uses tags on operations but never declares them at the root,
    so no tag carries a description.
  update:
    tags:
    - name: Categories
      description: The OwnLocal business category and sub-category vocabulary used to classify businesses and
        filter ads.
- target: $.paths['/api/v1/categories'].get
  description: Add operationId 'listCategories'. None of OwnLocal's 13 operations declares an operationId, which
    blocks code generation and leaves agent tooling with no stable handle. Assigned deterministically from the
    HTTP method and resource path.
  update:
    operationId: listCategories
- target: $.components.securitySchemes.apiKey
  description: 'Describe the apiKey scheme. The source declares type/name/in with no description, which omits
    the single most error-prone fact about this API: the key is sent RAW in the Authorization header with no Bearer
    prefix, and is issued manually by OwnLocal support. Stated in the published reference.'
  update:
    description: Organization API key sent raw (no scheme prefix) in the Authorization header. Keys are issued
      by OwnLocal support; there is no self-serve key provisioning.