yamlswaggeropenapi

OpenAPI - How to reference in schema to only one property of another schema?


I have the following OpenAPI in components --> schema. In CreateBookDto, I want to refer only to the id property of my Person schema. Is this possible with OpenAPI? If yes, how? If not, is there any reason why this feature does not exist?

Person:
      type: object
      properties:
        id:
          type: number
          description: ID of the person
        username:
          type: string
          description: Username of the person
        books:
          description: All books of one person
          type: array
          items:
            $ref: '#/components/schemas/Book'
CreateBookDto:
      type: object
      properties:
        title:
          type: string
          description: The title of the book
        person_id: <-- Here I want to reference to the id property of Person
          type: number
          description: The ID of the person

Solution

  • You can use a JSON pointer

    ...
    
    person_id:
      $ref: '#/components/schemas/Person/properties/id'
    
    ...