Is swagger's oneOf feature supported?

[joshuaballoch]

Hello!

First off, thanks for creating / maintaining this package. It's pretty great, I've been using it to document my API so far.

It's unclear to me if it's possible to define multiple schemas as possible schemas for a endpoint's request body. It seems to me that Swagger supports this: https://swagger.io/docs/specification/describing-request-body/#anyof--oneof-3

Is this possible to do with this library?

Just as an example, I have an endpoint in my API where user's get access tokens for accessing protected endpoints in the API. They can use two different grant types to do this, and so there is one schema possible for each grant type.

The Swagger example is pretty clear and concise too:

      requestBody:
        description: A JSON object containing pet information
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/Cat'
                - $ref: '#/components/schemas/Dog'
                - $ref: '#/components/schemas/Hamster'

[mbuhot]

@joshuaballoch phoenix_swagger currently targets version 2.0 of the swagger specification (https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md)

The version 2.0 spec doesn't support oneOf, but it does support discriminator: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#fixed-fields-13

[mbuhot]

Example usage of discriminator:

  def swagger_definitions do
    %{
      Event: swagger_schema do
        title "Event"
        description "A standard event envelope, containing a dynamic payload"
        discriminator "name"
        properties do
          name :string, "Event name that uniquely identifies the type of event", required: true
          timestamp :string, "Timestamp of event in originating system", format: :datetime, required: false
          key :string, "Unique key of event in originating system, used for deduplication", required: false
        end
      end,

      "email.opened": swagger_schema do
        title "email.opened"
        description "A recipient has opened an email."
        all_of [
          Schema.ref(:Event),
          Schema.new do
            property :payload, (Schema.new do
              property :id, :string, "The message id", required: true
              property :"user_agent.name", :string, "User agent name of the email client"
              property :"user_agent.type", :string, "User agent type of the email client"
              property :"user_agent.version", :string, "User agent version of the email client"
            end)
          end
        ]
      end
    }
  end

[joshuaballoch]

That's neat, I think that will fit my use case very well.

Thanks so much for the tips / help. I'll close this issue.

Out of curiosity, is there a more preferred way to ask these sorts of questions? Wasn't sure if there was another channel, and didn't feel so great about opening an issue as it was more a question than a feature request / bug report.

Again, thanks for the great work on the library.

[mbuhot]

Out of curiosity, is there a more preferred way to ask these sorts of questions?

Not really.

If you prefer, feel free to message me on the the Elixir slack, or start a thread in the elixir forum questions and help section, I've got the same username in both.

[joshuaballoch]

Hey @mbuhot, just curious - I've tried out your suggestion, but I encountered a couple issues. As background, my use-case is an endpoint where the request body could follow one of a set of request bodies that I've successfully described using the "discriminator" as suggested.

1. Is it possible to list multiple schemas as options for the request body of an endpoint? I thought of trying listing the schemas in a list where I had previously just listed one of them:

parameter :body, :body, [Schema.ref(:OneKindOfRequest), Schema.ref(:OtherKindOfRequest)], "The request body", example: %{type: "one_kind", foo: "bar"}

It doesn't seem like this is the right way to go about it, if this is even possible - as the UI page now doesn't display either model nor the example:

I'm not sure if that's just an issue with swagger UI though, the swagger.json output for listing these schemas was:

2. Is there an issue with Swagger UI's displaying of schemas defined as suggested using the discriminator? It seems like they display in the UI not as the name of the schema, but as the name of the base schema:

For reference, TokenRequest was the base schema, of which I had one sub schema defined called RefreshGrantRequest, with referred back to the TokenRequest schema.

This got to the swagger.json file fine, it seems:

Thank you for your help! Just trying to figure out how to do these things within the swagger / phoenix_swagger library.

[mbuhot]

Is it possible to list multiple schemas as options for the request body of an endpoint? I thought of trying listing the schemas in a list where I had previously just listed one of them:

I don't think so, in my application the usage is to refer to the 'base' schema:

  swagger_path(:create) do
    post "/events"
    summary "Publish an event"
    description "Publish an event to the Events API, to be processed asynchronously"
    parameter :event, :body, Schema.ref(:Event), "The event to publish", required: true
    tag :event
    operation_id :publish_event
    response 201, "The event was stored successfully"
  end

Is there an issue with Swagger UI's displaying of schemas defined as suggested using the discriminator? It seems like they display in the UI not as the name of the schema, but as the name of the base schema

Yes, I think this is a limitation in swagger-ui (swagger-api/swagger-ui#2438)