Support Components Section in OpenAPI Standard

[AkarinServer]

Describe the feature

According to the OpenAPI Standard, OpenAPI should support Components function.

Before using Components:

paths:
  /users/{userId}:
    get:
      summary: Get a user by ID
      parameters: ...
      responses:
        "200":
          description: A single user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
  /users:
    get:
      summary: Get all users
      responses:
        "200":
          description: A list of users.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string

After using components:

paths:
  /users/{userId}:
    get:
      summary: Get a user by ID
      parameters: ...
      responses:
        "200":
          description: A single user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
  /users:
    get:
      summary: Get all users
      responses:
        "200":
          description: A list of users.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

Hopefully can support this function soon.

Additional information

• Would you be willing to help implement this feature?

[OskarLebuda]

@AkarinServer what do you think about something like that?

defineRouteMeta({
  openAPI: {
    responses: {
      200: { description: 'OK ', content: { 'application/json': { schema: { $ref: '#/components/User' } } } },
    },
    components: {
      User: {
        type: 'object',
        properties: {
          id: { type: 'integer' },
          name: { type: 'string' },
        },
      }
    },
  },
});

export default eventHandler(async (event) => {
  return { hello: 'world!' };
});

It's a POC of components of the API. Let me know if it's something you're looking for.
Of course the User will be available later as a component so you will just use it like:

defineRouteMeta({
  openAPI: {
    responses: {
      200: { description: 'OK ', content: { 'application/json': { schema: { $ref: '#/components/User' } } } },
    },
  },
});

export default eventHandler(async (event) => {
  return { hello: 'world 2!' };
});

[AkarinServer]

Unbelievable! That's exactly what I'm describing! I'm so impressed for your support speed!!! Thanks for your awesome job!

[OskarLebuda]

Unbelievable! That's exactly what I'm describing! I'm so impressed for your support speed!!! Thanks for your awesome job!

Now we have to wait for the CR and PR approve 😄

[laplaceliu]

@AkarinServer what do you think about something like that?

defineRouteMeta({
  openAPI: {
    responses: {
      200: { description: 'OK ', content: { 'application/json': { schema: { $ref: '#/components/User' } } } },
    },
    components: {
      User: {
        type: 'object',
        properties: {
          id: { type: 'integer' },
          name: { type: 'string' },
        },
      }
    },
  },
});

export default eventHandler(async (event) => {
  return { hello: 'world!' };
});

It's a POC of components of the API. Let me know if it's something you're looking for. Of course the User will be available later as a component so you will just use it like:

defineRouteMeta({
  openAPI: {
    responses: {
      200: { description: 'OK ', content: { 'application/json': { schema: { $ref: '#/components/User' } } } },
    },
  },
});

export default eventHandler(async (event) => {
  return { hello: 'world 2!' };
});

I don't think this is a reasonable approach.

In fact, defineRouteMeta accepts a parameter of type NitroRouteMeta.

interface NitroRouteMeta {
    openAPI?: OperationObject;
}

The type of openAPI is OperationObject:

export interface OperationObject extends Extensable {
    tags?: string[];
    summary?: string;
    description?: string;
    externalDocs?: ExternalDocumentationObject;
    operationId?: string;
    parameters?: (ParameterObject | ReferenceObject)[];
    requestBody?: RequestBodyObject | ReferenceObject;
    responses?: ResponsesObject;
    callbacks?: Record<string, CallbackObject | ReferenceObject>;
    deprecated?: boolean;
    security?: SecurityRequirementObject[];
    servers?: ServerObject[];
}

As you can see, there is no field called components in OperationObject.

I think it is still necessary to find an openapi generator to see how components is implemented.

[OskarLebuda]

@laplaceliu look at that PR 💻
#2921

The NitroRouteMeta is extended