SwaggerUI does not recognize [:string, "null"] type used for JSONAPI prev/next links

[KronicDeth]

Using master

occurs because of json

"properties": {
        "links": {
          "type": "object",
          "properties": {
            "self": {
              "type": "string",
              "description": "Link to this page of results"
            },
            "prev": {
              "type": [
                "string",
                "null"
              ],
              "description": "Link to the previous page of results"
            },
            "next": {
              "type": [
                "string",
                "null"
              ],
              "description": "Link to the next page of results"
            },
            "last": {
              "type": "string",
              "description": "Link to the last page of results"
            },
            "first": {
              "type": "string",
              "description": "Link to the first page of results"
            }
          }
        },

which is generated by

phoenix_swagger/lib/phoenix_swagger/json_api.ex

Lines 68 to 75 in 0fc6e50

	prev: %Schema {
	type: [:string, "null"],
	description: "Link to the previous page of results"
	},
	next: %Schema {
	type: [:string, "null"],
	description: "Link to the next page of results"
	},

[mbuhot]

Where is the screenshot taken from?

The type ["string", "null"] is valid in JSON schema. Having just "string" will fail JSON schema validation if null is rendered in the output.

[KronicDeth]

It's taken from http://localhost:4000/docs/swagger/index.html#/Vehicle/Api_VehicleController_index, which routes from

defmodule Api.Router do
 # ...
 scope "/docs/swagger" do
    forward "/", PhoenixSwagger.Plug.SwaggerUI, otp_app: :api, swagger_file: "swagger.json"
  end
  # ...
end

using Api.VehicleController

defmodule Api.VehicleController do
  # ...
  swagger_path :index do # no cover
    get path(__MODULE__, :index)
    description """
    List of vehicles (buses, ferries, and trains)

    ## Direction

    ### World

    To figure out which way vehicles are pointing at the location, use `data/{index}/attributes/bearing`.  This can be \
    the compass bearing, or the direction towards the next stop or intermediate location.

    ### Trip

    To get the direction around the stops in each vehicle's trip use `data/{index}/attributes/direction`.

    ## Location

    ### World

    Use `data/{index}/attributes/latitude` and `data/{index}/attributes/longitude` to get the location of vehicles.

    ### Trip

    Use `data/{index}/attributes/current_stop_sequence` to get the stop number along the trip.  Useful for linear \
    stop indicators.  Position relative to the current stop is in `data/{index}/attributes/current_status`.

    ## Movement

    ### World

    Use `data/{index}/attributes/speed` to get the speed of the vehicle in meters per second.

    """

    common_index_parameters(__MODULE__)
    include_parameters(~w(trip stop route))
    filter_param(:id, name: :trip)
    filter_param(:id, name: :route)
    filter_param(:direction_id)

    response 200, "OK", Schema.ref(:Vehicles)
  end

  def swagger_definitions do # no cover
    import PhoenixSwagger.JsonApi, except: [page: 1]

    %{ # no cover
      VehicleResource: resource do # no cover
        description "Current state of a vehicle on a trip."
        attributes do # no cover
          id :string,
             "Unique ID for vehicle.  Used in API.  NOT for End-Users.  See [GTFS-realtime VehicleDescriptor id](https://github.com/google/transit/blob/master/gtfs-realtime/spec/en/reference.md#message-vehicledescriptor).",
             example: "1817"
          bearing :integer,
                  "Bearing, in degrees, clockwise from True North, i.e., 0 is North and 90 is East. This can be the compass bearing, or the direction towards the next stop or intermediate location. See [GTFS-realtime Position bearing](https://github.com/google/transit/blob/master/gtfs-realtime/spec/en/reference.md#message-position).",
                  example: 174
          current_status :string,
                         """
                         Status of vehicle relative to the stops. See [GTFS-realtime VehicleStopStatus](https://github.com/google/transit/blob/master/gtfs-realtime/spec/en/reference.md#enum-vehiclestopstatus).


                         | _**Value**_       | _**Description**_                                                                                          |
                         |-------------------|------------------------------------------------------------------------------------------------------------|
                         | **INCOMING_AT**   | The vehicle is just about to arrive at the stop (on a stop display, the vehicle symbol typically flashes). |
                         | **STOPPED_AT**    | The vehicle is standing at the stop.                                                                       |
                         | **IN_TRANSIT_TO** | The vehicle has departed the previous stop and is in transit.                                              |

                         """,
                         example: "IN_TRANSIT_TO"
          current_stop_sequence :integer,
                                "Index of current stop along trip. See [GTFS-realtime VehiclePosition current_stop_sequence](https://github.com/google/transit/blob/master/gtfs-realtime/spec/en/reference.md#message-vehicleposition)",
                                example: 8
          direction_id :integer, "Direction of travel of the vehicle: 0, 1", example: "1"
          label :string,
                "User visible label, such as the one of on the signage on the vehicle.  See [GTFS-realtime VehicleDescriptor label](https://github.com/google/transit/blob/master/gtfs-realtime/spec/en/reference.md#message-vehicledescriptor).",
                example: "1817"
          last_updated %Schema{type: :string, format: :datetime},
                       "Time at which vehicle information was last updated",
                       example: "2017-08-14T16:04:44-04:00"
          latitude :number,
                   "Latitude of the vehicle's current position. Degrees North, in the [WGS-84](https://en.wikipedia.org/wiki/World_Geodetic_System#A_new_World_Geodetic_System:_WGS.C2.A084) coordinate system. See [GTFS-realtime Position latitude](https://github.com/google/transit/blob/master/gtfs-realtime/spec/en/reference.md#message-position).",
                   example: -71.27239990234375
          longitude :number,
                    "Longitude of the vehicle's current position.  Degrees East, in the [WGS-84](Degrees East, in the WGS-84 coordinate system.) coordinate system. See [GTFS-realtime Position longitude](https://github.com/google/transit/blob/master/gtfs-realtime/spec/en/reference.md#message-position).",
                    example: 42.32941818237305
          speed :number,
                "Speed that the vehicle is traveling in meters per second. See [GTFS-realtime Position speed](https://github.com/google/transit/blob/master/gtfs-realtime/spec/en/reference.md#message-position).",
                example: 16
        end
        relationship :trip
        relationship :stop
        relationship :route
      end,
      Vehicle: single(:VehicleResource),
      Vehicles: page(:VehicleResource)
    }
  end
  # ...
end

[mbuhot]

Looks like this is one of the cases where swagger and json-schema differ.

It's been raised on the swaggerui repo too (swagger-api/swagger-ui#1920) but looks like it isn't allowed by the swagger 2.0 spec.

👍