Update OpenApiSpex docs

dhrdlicka · dhrdlicka · commit 4ef629156bc4 · 2024-02-19T13:33:46.000+01:00
diff --git a/lib/swapi_web/controllers/film_controller.ex b/lib/swapi_web/controllers/film_controller.ex
@@ -2,6 +2,7 @@ defmodule SWAPIWeb.FilmController do
   use SWAPIWeb, :controller
   use OpenApiSpex.ControllerSpecs
 
+  alias OpenApiSpex.Schema
   alias SWAPI.Films
 
   import SWAPIWeb.Util
@@ -19,7 +20,32 @@ defmodule SWAPIWeb.FilmController do
           "One or more search terms, which should be whitespace and/or comma separated. If multiple search terms are used then objects will be returned in the list only if all the provided terms are matched. Searches may contain quoted phrases with spaces, each phrase is considered as a single search term.",
         type: :string
       ],
-      page: [in: :query, description: "Page number", type: :integer]
+      page: [
+        in: :query,
+        description: "Page number. Cannot be used together with `offset`.",
+        schema: %Schema{
+          type: :integer,
+          minimum: 1,
+          default: 1
+        }
+      ],
+      offset: [
+        in: :query,
+        description: "Offset of the first item. Cannot be used together with `page`.",
+        schema: %Schema{
+          type: :integer,
+          minimum: 0
+        }
+      ],
+      limit: [
+        in: :query,
+        description: "Maximum number of items to return in the response.",
+        schema: %Schema{
+          type: :integer,
+          minimum: 1,
+          default: 10
+        }
+      ]
     ],
     responses: [
       ok: {"List of films", "application/json", SWAPIWeb.Schemas.FilmList}
diff --git a/lib/swapi_web/controllers/person_controller.ex b/lib/swapi_web/controllers/person_controller.ex
@@ -2,6 +2,7 @@ defmodule SWAPIWeb.PersonController do
   use SWAPIWeb, :controller
   use OpenApiSpex.ControllerSpecs
 
+  alias OpenApiSpex.Schema
   alias SWAPI.People
 
   import SWAPIWeb.Util
@@ -19,7 +20,32 @@ defmodule SWAPIWeb.PersonController do
           "One or more search terms, which should be whitespace and/or comma separated. If multiple search terms are used then objects will be returned in the list only if all the provided terms are matched. Searches may contain quoted phrases with spaces, each phrase is considered as a single search term.",
         type: :string
       ],
-      page: [in: :query, description: "Page number", type: :integer]
+      page: [
+        in: :query,
+        description: "Page number. Cannot be used together with `offset`.",
+        schema: %Schema{
+          type: :integer,
+          minimum: 1,
+          default: 1
+        }
+      ],
+      offset: [
+        in: :query,
+        description: "Offset of the first item. Cannot be used together with `page`.",
+        schema: %Schema{
+          type: :integer,
+          minimum: 0
+        }
+      ],
+      limit: [
+        in: :query,
+        description: "Maximum number of items to return in the response.",
+        schema: %Schema{
+          type: :integer,
+          minimum: 1,
+          default: 10
+        }
+      ]
     ],
     responses: [
       ok: {"List of people", "application/json", SWAPIWeb.Schemas.PersonList}
diff --git a/lib/swapi_web/controllers/planet_controller.ex b/lib/swapi_web/controllers/planet_controller.ex
@@ -2,6 +2,7 @@ defmodule SWAPIWeb.PlanetController do
   use SWAPIWeb, :controller
   use OpenApiSpex.ControllerSpecs
 
+  alias OpenApiSpex.Schema
   alias SWAPI.Planets
 
   import SWAPIWeb.Util
@@ -19,7 +20,32 @@ defmodule SWAPIWeb.PlanetController do
           "One or more search terms, which should be whitespace and/or comma separated. If multiple search terms are used then objects will be returned in the list only if all the provided terms are matched. Searches may contain quoted phrases with spaces, each phrase is considered as a single search term.",
         type: :string
       ],
-      page: [in: :query, description: "Page number", type: :integer]
+      page: [
+        in: :query,
+        description: "Page number. Cannot be used together with `offset`.",
+        schema: %Schema{
+          type: :integer,
+          minimum: 1,
+          default: 1
+        }
+      ],
+      offset: [
+        in: :query,
+        description: "Offset of the first item. Cannot be used together with `page`.",
+        schema: %Schema{
+          type: :integer,
+          minimum: 0
+        }
+      ],
+      limit: [
+        in: :query,
+        description: "Maximum number of items to return in the response.",
+        schema: %Schema{
+          type: :integer,
+          minimum: 1,
+          default: 10
+        }
+      ]
     ],
     responses: [
       ok: {"List of planets", "application/json", SWAPIWeb.Schemas.PlanetList}
diff --git a/lib/swapi_web/controllers/species_controller.ex b/lib/swapi_web/controllers/species_controller.ex
@@ -2,6 +2,7 @@ defmodule SWAPIWeb.SpeciesController do
   use SWAPIWeb, :controller
   use OpenApiSpex.ControllerSpecs
 
+  alias OpenApiSpex.Schema
   alias SWAPI.Species
 
   import SWAPIWeb.Util
@@ -19,7 +20,32 @@ defmodule SWAPIWeb.SpeciesController do
           "One or more search terms, which should be whitespace and/or comma separated. If multiple search terms are used then objects will be returned in the list only if all the provided terms are matched. Searches may contain quoted phrases with spaces, each phrase is considered as a single search term.",
         type: :string
       ],
-      page: [in: :query, description: "Page number", type: :integer]
+      page: [
+        in: :query,
+        description: "Page number. Cannot be used together with `offset`.",
+        schema: %Schema{
+          type: :integer,
+          minimum: 1,
+          default: 1
+        }
+      ],
+      offset: [
+        in: :query,
+        description: "Offset of the first item. Cannot be used together with `page`.",
+        schema: %Schema{
+          type: :integer,
+          minimum: 0
+        }
+      ],
+      limit: [
+        in: :query,
+        description: "Maximum number of items to return in the response.",
+        schema: %Schema{
+          type: :integer,
+          minimum: 1,
+          default: 10
+        }
+      ]
     ],
     responses: [
       ok: {"List of species", "application/json", SWAPIWeb.Schemas.SpeciesList}
diff --git a/lib/swapi_web/controllers/starship_controller.ex b/lib/swapi_web/controllers/starship_controller.ex
@@ -2,6 +2,7 @@ defmodule SWAPIWeb.StarshipController do
   use SWAPIWeb, :controller
   use OpenApiSpex.ControllerSpecs
 
+  alias OpenApiSpex.Schema
   alias SWAPI.Starships
 
   import SWAPIWeb.Util
@@ -19,7 +20,32 @@ defmodule SWAPIWeb.StarshipController do
           "One or more search terms, which should be whitespace and/or comma separated. If multiple search terms are used then objects will be returned in the list only if all the provided terms are matched. Searches may contain quoted phrases with spaces, each phrase is considered as a single search term.",
         type: :string
       ],
-      page: [in: :query, description: "Page number", type: :integer]
+      page: [
+        in: :query,
+        description: "Page number. Cannot be used together with `offset`.",
+        schema: %Schema{
+          type: :integer,
+          minimum: 1,
+          default: 1
+        }
+      ],
+      offset: [
+        in: :query,
+        description: "Offset of the first item. Cannot be used together with `page`.",
+        schema: %Schema{
+          type: :integer,
+          minimum: 0
+        }
+      ],
+      limit: [
+        in: :query,
+        description: "Maximum number of items to return in the response.",
+        schema: %Schema{
+          type: :integer,
+          minimum: 1,
+          default: 10
+        }
+      ]
     ],
     responses: [
       ok: {"List of starships", "application/json", SWAPIWeb.Schemas.StarshipList}
diff --git a/lib/swapi_web/controllers/vehicle_controller.ex b/lib/swapi_web/controllers/vehicle_controller.ex
@@ -2,6 +2,7 @@ defmodule SWAPIWeb.VehicleController do
   use SWAPIWeb, :controller
   use OpenApiSpex.ControllerSpecs
 
+  alias OpenApiSpex.Schema
   alias SWAPI.Vehicles
 
   import SWAPIWeb.Util
@@ -19,7 +20,32 @@ defmodule SWAPIWeb.VehicleController do
           "One or more search terms, which should be whitespace and/or comma separated. If multiple search terms are used then objects will be returned in the list only if all the provided terms are matched. Searches may contain quoted phrases with spaces, each phrase is considered as a single search term.",
         type: :string
       ],
-      page: [in: :query, description: "Page number", type: :integer]
+      page: [
+        in: :query,
+        description: "Page number. Cannot be used together with `offset`.",
+        schema: %Schema{
+          type: :integer,
+          minimum: 1,
+          default: 1
+        }
+      ],
+      offset: [
+        in: :query,
+        description: "Offset of the first item. Cannot be used together with `page`.",
+        schema: %Schema{
+          type: :integer,
+          minimum: 0
+        }
+      ],
+      limit: [
+        in: :query,
+        description: "Maximum number of items to return in the response.",
+        schema: %Schema{
+          type: :integer,
+          minimum: 1,
+          default: 10
+        }
+      ]
     ],
     responses: [
       ok: {"List of vehicles", "application/json", SWAPIWeb.Schemas.VehicleList}
