OpenAPI: update usage of tags.

[Goldziher]

See the related issue in pydantic-openapi-schema - usage of tags is currently wrong, so we need to update that library, and then our usage.

I also suggest we make tags layered like other elements.

[Goldziher]

So more info. The OpenAPI 3.1 specs define tags as a json array of "tag" objects. See respectively- https://spec.openapis.org/oas/latest.html#schema-object and https://spec.openapis.org/oas/latest.html#tag-object.

The library we forked and released as pydantic-openapi-schema does define a Tag class correctly but it doesn't use it in the Schema class and any other place it might be required (needs to be checked in the OA specs).

So the task in this issue is dual- 1. Update that library. You can than locally develop starlite by installing your branch of that lib. Then starlite needs to update it's use of Tags somehow.

I would suggest allowing users to pass either a string or a Tag object, and under the hood convert strings to Tag objects when not provided.

Anyhow, the docs will need some refreshing as well on the usage if Tags etc.

[seladb]

Thanks @Goldziher for the info!

I'm not sure how Tag relates to Schema. The Tag objects are defined in OA root, and then each operation can refer to one or more tags. This reference is done through a string.

Here is an example:

openapi: "3.1.0"
info:
  title: Example
  version: "1.0"
paths:
  /item:
    get:
      parameters: 
      - name: "id"
        description: "Item id"
        in: path
        required: true
      tags: 
        - Tag1
tags: 
- name: "Tag1"
  description: "This is Tag1"

Here is how the reference is done in pydantic-openapi-schema: https://github.com/starlite-api/pydantic-openapi-schema/blob/ae642fd32f17429aa0ce8b7a8c8055201f458129/pydantic_openapi_schema/v3_1_0/operation.py#L18

My understanding is that Schema is a different object that allows defining reusable elements or objects, for example:

openapi: "3.1.0"
info:
  title: Example
  version: "1.0"
paths:
  /item:
    post:
      parameters: 
      - name: "name"
        description: "Item name"
        in: query
        required: true
      responses:
        200:
          description: "Successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/success"
        401:
          description: "Error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
components:
  schemas:
    success:
      title: "Successful response"
      properties:
        statusCode:
          default: 200
    error:
      title: "Error response"
      type: object
      properties:
        errorCode:
          type: integer
          default: 401
        errorDescription:
          type: string

I don't think Schema can use a Tag

I'm pretty sure I'm missing something, can you please help me understand what it is?

[Goldziher]

Actually, I was totally wrong it seems. I misunderstood the spec. Closing this one. Sorry for wasting your time @seladb