OpenAPI V2 schema definition for `/products` response is broken

API
, ,
1

There seems to be some erroneous double nesting defined in the OpenAPI v2 bundle for `/products` GET endpoint response - notice the nested data → data arrays due to the extra GetProductResponse object which shouldn’t exist there at all:

schema:                                                                                
  title: GetProductsResponse                                                           
  type: object                                                                         
  properties:                                                                          
    success:                                                                           
      type: boolean                                                                    
    data:                                                                              
      type: array                                                                      
      items:                                                                           
        title: GetProductResponse                                                      
        type: object                                                                   
        properties:                                                                    
          success:                                                                     
            type: boolean                                                              
          data:                                                                        
            - title: BaseProduct
              allOf:
                - type: Object
                  properties:
                  # ... properties for `Product`

Based on currently provided schema, OpenAPI-based tooling expects data with following structure:

{'success': true, data: [
    {'success': true, 'data': [{ product_object }]},
    {'success': true, 'data': [{ product_object }]},
    ...
],
...
}

Also, the BaseProduct is missing some properties (add_time, update_time, description, category).

Here’s one way to fix the bundle to correspond to real data from endpoint:

yq -i '
  .paths."/products".get.responses."200".content."application/json".schema.properties.data as $d |
  .paths."/products".get.responses."200".content."application/json".schema.properties.data.items = (
    $d.items.properties.data.allOf[0] |
    .allOf[0].properties += {
      "add_time": {"type": "string"},
      "update_time": {"type": "string"},
      "description": {"type": "string"},
      "category": {"type": "string"}
    }
)
' openapi-v2.yaml

Few more issues:

  • There’s no support to query changed products by updated_since :frowning:
  • The .prices property (this is actually dropped by my custom patch) is lacking object structure.
  • Linking products to deals? (Properly syncing these many2many objects)