OpenApiSpex schema - are there any naming conventions on handling show and index routes?

Questions & Help Questions
1

Hi all,

I was wondering if there is any naming convention on handling show and index routes. Would they just fall under Request and Response?

If i have a show route for getting a car by id

would it be something like

show naming:


defmodule CarRequest do
  require OpenApiSpex
  alias OpenApiSpex.Schema
  
  OpenApiSpex.schema(%{
    title: "CarRequest",
    description: "Gets a single car by id.",
    type: :object,
    required: [:id],
    properties: %{
      id: %Schema{type: :integer, example: 12}
    }
  })
end

index naming:

defmodule CarsRequest do
  require OpenApiSpex
  alias OpenApiSpex.Schema
  
  OpenApiSpex.schema(%{
    title: "CarsRequest",
    description: "Gets all cars.",
    type: :object
  })
end

then inside of the response would it be something like

defmodule CarResponse do
  require OpenApiSpex
  alias OpenApiSpex.Schema
  
  OpenApiSpex.schema(%{
    title: "CarResponse",
    description: "Gets a single car.",
    type: :object,
    required: [:data],
    properties: %{
      data: Car.schema()
    }
  })
end

index response

defmodule CarsResponse do
  require OpenApiSpex
  alias OpenApiSpex.Schema
  
  OpenApiSpex.schema(%{
    title: "CarsResponse",
    description: "Gets all cars.",
    type: :object,
    required: [:data],
    properties: %{
      data: %Schema{type: :array, data: Car.schema()}
    }
  })
end

shared Car response:

defmodule Car do
  require OpenApiSpex
  alias OpenApiSpex.Schema
  
  OpenApiSpex.schema(%{
    title: "Car",
    description: "A single car.",
    type: :object,
    required: [:id, :make, :model],
    properties: %{
      id: %Schema{type: :integer, example: 12},
      make: %Schema{type: :string, example: "toyota"},
      model: %Schema{type: :string, example: "corolla"}
    }
  })
end
1 Like