Response schema missing from Swagger api description?

[thomas001le]

Hello everybody.

I was instantly hooked when I learned that fitbit offers a Web API to export timeseries. I am still not entirely sure what I want to do with the data, but I have several ideas in my mind. Anyway, here my actual question:

The Web API has a Swagger description file (available here: https://dev.fitbit.com/build/reference/web-api/explore/). Unfortunately, it seems incomplete. The responses are missing a result type schema ("Response Body" in https://swagger.io/docs/specification/2-0/describing-responses/). Why is this useful? There are Swagger client generators for several languages, those generate easy-to-use client libraries from the swagger file. Unfortunately, those generators can't work correctly if the swagger file is incomplete.

Is there any plan to comple the swagger API description?

[Gordon-C]

Hi @thomas001le 

Would you please provide me with some examples where the information in the https://dev.fitbit.com/build/reference/web-api/explore/fitbit-web-api-swagger.json is missing?   I'll see if it is possible for use to fix it.

Thanks!

Gordon

[thomas001le]

I tried to add schema information to one of the calls. Only the "schema" information was added, the rest it taken from the existing json file. I tried to derive the schema from the example here: https://dev.fitbit.com/build/reference/web-api/heart-rate/#get-heart-rate-time-series. But some types were not mentioned in the example, customHeartRateZones is missing (it's an array, but of what?).

        "/1/user/-/activities/heart/date/{date}/{period}.json": {
            "get": {
                "tags": [
                    "Heart Rate Time Series"
                ],
                "summary": "Get Heart Rate Time Series",
                "description": "Returns the time series data in the specified range for a given resource in the format requested using units in the unit systems that corresponds to the Accept-Language head
er provided.",
                "operationId": "getHeartByDatePeriod",
                "produces": [
                    "application/json"
                ],
                "parameters": [
                    {
                        "name": "date",
                        "in": "path",
                        "description": "The end date of the period specified in the format yyyy-MM-dd or today.",
                        "required": true,
                        "type": "string",
                        "format": "date"
                    },
                    {
                        "name": "period",
                        "in": "path",
                        "description": "The range of which data will be returned. Options are 1d, 7d, 30d, 1w, and 1m.",
                        "required": true,
                        "type": "string"
                    }
                ],
                "responses": {
                  "200": {
                    "description": "Successful request.",
                    "schema": {
                      "type": "object",
                      "properties": {
                        "activities-heart": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "dateTime": {
                                "type": "string"
                              },
                              "value": {
                                "type": "object",
                                "properties": {
                                  "customHeartRateZones": {
                                    "type": "array",
                                    "items": {
                                      "type": "object"
                                    }
                                  },
                                  "heartRateZones": {
                                    "type": "object",
                                    "properties": {
                                      "caloriesOut": {
                                        "type": "number"
                                      },
                                      "max": {
                                        "type": "number"
                                      },
                                      "min": {
                                        "type": "number"
                                      },
                                      "minutes": {
                                        "type": "number"
                                      },
                                      "name": {
                                        "type": "string"
                                      }
                                    }
                                  }
                                }
                              },
                              "restingHeartRate": {
                                "type": "number"
                              }
                            }
                          }
                        }
                      }
                    }
                  },
                    "401": {
                        "description": "The request requires user authentication."
                    },
                    "403": {
                        "description": "The server understood the request, but is refusing to fulfill it."
                    }
                },
                "security": [
                    {
                        "oauth2": [
                            "activity",
                            "heartrate",
                            "location",
                            "nutrition",
                            "profile",
                            "settings",
                            "sleep",
                            "social",
                            "weight"
                        ]
                    }
                ]
            }
        },

With that information code generator automatically generate data structures for responses and automatically convert json to a language native type.