paths:
  summary: "Interact with one entity within a namespace"
  delete:
    description: "Delete an existing entity"
    tags:
    - entities
    parameters:
    - $ref: "#/components/parameters/token"
    - $ref: "#/components/parameters/id"
    responses:
      200:
        $ref: "#/components/schemas/responseOK"

  get:
    description: "Get an existing entity"
    tags:
    - entities
    parameters:
    - $ref: "#/components/parameters/token"
    - $ref: "#/components/parameters/id"
    - $ref: "#/components/parameters/md"
    responses:
      200:
        $ref: "#/components/schemas/responseOneResolved"

  put:
    description: "Replace an existing entity"
    tags:
    - entities
    parameters:
    - $ref: "#/components/parameters/token"
    - $ref: "#/components/parameters/id"
    requestBody:
      $ref: "#/components/schemas/requestOne"
    responses:
      200:
        $ref: "#/components/schemas/responseOne"

  patch:
    description: "Update an existing entity"
    tags:
    - entities
    parameters:
    - $ref: "#/components/parameters/token"
    - $ref: "#/components/parameters/id"
    requestBody:
      $ref: "#/components/schemas/requestOne"
    responses:
      200:
        $ref: "#/components/schemas/responseOne"

components:
  parameters:
    token:
      $ref: "../swagger.yaml#/components/parameters/token"
    id:
      $ref: "../swagger.yaml#/components/parameters/id"
    md:
      name: md
      description: "render the text section as markdown"
      in: query
      required: false
      schema:
        type: bool

  schemas:
    requestOne:
      $ref: "../swagger.yaml#/components/schemas/requestOne"
    responseOne:
      $ref: "../swagger.yaml#/components/schemas/responseOne"
    responseOneResolved:
      $ref: "../swagger.yaml#/components/schemas/responseOneResolved"
    responseOK:
      $ref: "../swagger.yaml#/components/schemas/responseOK"