37

How can I best describe a generic response type which includes the real data type in OpenAPI 3.

Simplified example:

ApiResponse:
  data: object
  error: string

But the /users endpoint should give:

ApiResponse<List<User>>

So that basically is:

ApiResponse:
  data: List<User>
  error: string

It looks like this is not possible at the moment, but just want to make sure. I guess the best way to do this now is to make named responses for every call and use allOf to refer to ApiResponse and implemenent data: specific value.

Jørgen
  • 2,157
  • 1
  • 23
  • 24

2 Answers2

36

I search for generic types much time, but there is no way to define a generic type in OpenAPI3. The simplest way is using allOf and $ref at the same time. Suppose there is a list schema as follow:

List:
   type: object
   properties:
       page_number:
          type: integer
       page_count:
          type: integer

And the book schema is

Book:
   type: object
   properties:
       title:
          type: string
       summary:
          type: string

To return a list, the path is:

  /api/v1/books:
      get:
        responses:
          default:  
            description: description text
            content:
              application/json:
                schema:
                  allOf:
                    - $ref: '#/components/schemas/List'
                    - type: object
                      properties:
                        items: 
                          type: array
                          items: 
                            $ref: '#/components/schemas/Book'

Thie result is

   {
        "page_number": 1,
        "page_count": 10,
        "items": [{
            "title": "title",
            "description": ""
        },
        ... ]
    }

Actually, this is a list of books. As you can see, you add main attributes of the list to the result and list item type at the same time. You can repeat this pattern for others too:

  /api/v1/authors:
      get:
        responses:
          default:  
            description: description text
            content:
              application/json:
                schema:
                  allOf:
                    - $ref: '#/components/schemas/List'
                    - type: object
                      properties:
                        items: 
                          type: array
                          items: 
                            $ref: '#/components/schemas/Author'
Mostafa Barmshory
  • 1,849
  • 24
  • 39
  • It is checked on Swagger Hub – Mostafa Barmshory Aug 06 '18 at 10:58
  • 7
    in OAS 3 `[main] WARN o.o.codegen.DefaultCodegen - allOf with multiple schemas defined. Using only the first one: List` – schemacs Jun 08 '20 at 06:35
  • 1
    The controller class generated from this only seems to return one of the items defined under allOf although it looks correct in the generated Doc. I think this does not work. At least for Java Spring code gen. – froehr Oct 20 '20 at 15:37
  • This approach is also documented in the specification: https://swagger.io/specification/#composition-and-inheritance-polymorphism – justfortherec Nov 02 '20 at 16:29
-4

Well, you can use type object with additionalProperties with true value to get free form objects.

Pablo Santa Cruz
  • 176,835
  • 32
  • 241
  • 292