Skip to content

Instantly share code, notes, and snippets.

@ryan-blunden
Created July 14, 2025 05:52
Show Gist options
  • Save ryan-blunden/33209694fe772b6c485d08be58abfed5 to your computer and use it in GitHub Desktop.
Save ryan-blunden/33209694fe772b6c485d08be58abfed5 to your computer and use it in GitHub Desktop.
StarWars OpenAPI
openapi: 3.1.0
info:
title: SWAPI - The Star Wars API
description: |
SWAPI (Star Wars API) is a RESTful API that provides comprehensive data about the Star Wars universe.
This API includes information about films, people, planets, species, starships, and vehicles from the Star Wars saga.
All endpoints are read-only and return JSON data. The API is hosted on a highly available CDN network
for fast response times and high reliability.
version: 1.0.0
contact:
name: SWAPI.INFO
url: https://swapi.info
license:
name: MIT
url: https://github.com/swapi-info/swapi-info/blob/main/LICENSE
servers:
- url: https://swapi.info/api
description: Production server
paths:
/:
get:
summary: Get API root
description: Returns the root resource with links to all available resource categories
operationId: getRoot
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Root'
example:
films: "https://swapi.info/api/films"
people: "https://swapi.info/api/people"
planets: "https://swapi.info/api/planets"
species: "https://swapi.info/api/species"
vehicles: "https://swapi.info/api/vehicles"
starships: "https://swapi.info/api/starships"
/films:
get:
summary: Get all films
description: Returns a list of all Star Wars films
operationId: getAllFilms
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Film'
/films/{id}:
get:
summary: Get a specific film
description: Returns a specific film by ID
operationId: getFilm
parameters:
- name: id
in: path
required: true
description: The ID of the film to retrieve
schema:
type: integer
minimum: 1
maximum: 6
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Film'
'404':
description: Film not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
detail: "Not found"
/films/schema:
get:
summary: Get film schema
description: Returns the JSON schema for film resources
operationId: getFilmSchema
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
/people:
get:
summary: Get all people
description: Returns a list of all people in the Star Wars universe
operationId: getAllPeople
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Person'
/people/{id}:
get:
summary: Get a specific person
description: Returns a specific person by ID
operationId: getPerson
parameters:
- name: id
in: path
required: true
description: The ID of the person to retrieve
schema:
type: integer
minimum: 1
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Person'
'404':
description: Person not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
detail: "Not found"
/people/schema:
get:
summary: Get people schema
description: Returns the JSON schema for people resources
operationId: getPeopleSchema
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
/planets:
get:
summary: Get all planets
description: Returns a list of all planets in the Star Wars universe
operationId: getAllPlanets
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Planet'
/planets/{id}:
get:
summary: Get a specific planet
description: Returns a specific planet by ID
operationId: getPlanet
parameters:
- name: id
in: path
required: true
description: The ID of the planet to retrieve
schema:
type: integer
minimum: 1
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Planet'
'404':
description: Planet not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
detail: "Not found"
/planets/schema:
get:
summary: Get planets schema
description: Returns the JSON schema for planet resources
operationId: getPlanetsSchema
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
/species:
get:
summary: Get all species
description: Returns a list of all species in the Star Wars universe
operationId: getAllSpecies
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Species'
/species/{id}:
get:
summary: Get a specific species
description: Returns a specific species by ID
operationId: getSpecies
parameters:
- name: id
in: path
required: true
description: The ID of the species to retrieve
schema:
type: integer
minimum: 1
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Species'
'404':
description: Species not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
detail: "Not found"
/species/schema:
get:
summary: Get species schema
description: Returns the JSON schema for species resources
operationId: getSpeciesSchema
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
/starships:
get:
summary: Get all starships
description: Returns a list of all starships in the Star Wars universe
operationId: getAllStarships
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Starship'
/starships/{id}:
get:
summary: Get a specific starship
description: Returns a specific starship by ID
operationId: getStarship
parameters:
- name: id
in: path
required: true
description: The ID of the starship to retrieve
schema:
type: integer
minimum: 1
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Starship'
'404':
description: Starship not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
detail: "Not found"
/starships/schema:
get:
summary: Get starships schema
description: Returns the JSON schema for starship resources
operationId: getStarshipsSchema
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
/vehicles:
get:
summary: Get all vehicles
description: Returns a list of all vehicles in the Star Wars universe
operationId: getAllVehicles
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Vehicle'
/vehicles/{id}:
get:
summary: Get a specific vehicle
description: Returns a specific vehicle by ID
operationId: getVehicle
parameters:
- name: id
in: path
required: true
description: The ID of the vehicle to retrieve
schema:
type: integer
minimum: 1
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Vehicle'
'404':
description: Vehicle not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
detail: "Not found"
/vehicles/schema:
get:
summary: Get vehicles schema
description: Returns the JSON schema for vehicle resources
operationId: getVehiclesSchema
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
components:
schemas:
Root:
type: object
description: The root resource containing links to all available resource categories
properties:
films:
type: string
format: uri
description: URL to the films resource
example: "https://swapi.info/api/films"
people:
type: string
format: uri
description: URL to the people resource
example: "https://swapi.info/api/people"
planets:
type: string
format: uri
description: URL to the planets resource
example: "https://swapi.info/api/planets"
species:
type: string
format: uri
description: URL to the species resource
example: "https://swapi.info/api/species"
vehicles:
type: string
format: uri
description: URL to the vehicles resource
example: "https://swapi.info/api/vehicles"
starships:
type: string
format: uri
description: URL to the starships resource
example: "https://swapi.info/api/starships"
required:
- films
- people
- planets
- species
- vehicles
- starships
Film:
type: object
description: A Star Wars film
properties:
title:
type: string
description: The title of this film
example: "A New Hope"
episode_id:
type: integer
description: The episode number of this film
example: 4
opening_crawl:
type: string
description: The opening paragraphs at the beginning of this film
director:
type: string
description: The name of the director of this film
example: "George Lucas"
producer:
type: string
description: The name(s) of the producer(s) of this film
example: "Gary Kurtz, Rick McCallum"
release_date:
type: string
format: date
description: The ISO 8601 date format of film release at original creator country
example: "1977-05-25"
characters:
type: array
description: An array of people resource URLs that are in this film
items:
type: string
format: uri
example: "https://swapi.info/api/people/1"
planets:
type: array
description: An array of planet resource URLs that are in this film
items:
type: string
format: uri
example: "https://swapi.info/api/planets/1"
starships:
type: array
description: An array of starship resource URLs that are in this film
items:
type: string
format: uri
example: "https://swapi.info/api/starships/2"
vehicles:
type: array
description: An array of vehicle resource URLs that are in this film
items:
type: string
format: uri
example: "https://swapi.info/api/vehicles/4"
species:
type: array
description: An array of species resource URLs that are in this film
items:
type: string
format: uri
example: "https://swapi.info/api/species/1"
created:
type: string
format: date-time
description: The ISO 8601 date format of the time that this resource was created
example: "2014-12-10T14:23:31.880000Z"
edited:
type: string
format: date-time
description: The ISO 8601 date format of the time that this resource was edited
example: "2014-12-20T19:49:45.256000Z"
url:
type: string
format: uri
description: The hypermedia URL of this resource
example: "https://swapi.info/api/films/1"
required:
- title
- episode_id
- opening_crawl
- director
- producer
- release_date
- characters
- planets
- starships
- vehicles
- species
- created
- edited
- url
Person:
type: object
description: A person within the Star Wars universe
properties:
name:
type: string
description: The name of this person
example: "Luke Skywalker"
height:
type: string
description: The height of the person in centimeters
example: "172"
mass:
type: string
description: The mass of the person in kilograms
example: "77"
hair_color:
type: string
description: The hair color of this person
example: "blond"
skin_color:
type: string
description: The skin color of this person
example: "fair"
eye_color:
type: string
description: The eye color of this person
example: "blue"
birth_year:
type: string
description: The birth year of the person, using the in-universe standard of BBY or ABY
example: "19BBY"
gender:
type: string
description: The gender of this person
example: "male"
homeworld:
type: string
format: uri
description: The URL of a planet resource, a planet that this person was born on or inhabits
example: "https://swapi.info/api/planets/1"
films:
type: array
description: An array of film resource URLs that this person has been in
items:
type: string
format: uri
example: "https://swapi.info/api/films/1"
species:
type: array
description: An array of species resource URLs that this person belongs to
items:
type: string
format: uri
example: "https://swapi.info/api/species/1"
vehicles:
type: array
description: An array of vehicle resource URLs that this person has piloted
items:
type: string
format: uri
example: "https://swapi.info/api/vehicles/14"
starships:
type: array
description: An array of starship resource URLs that this person has piloted
items:
type: string
format: uri
example: "https://swapi.info/api/starships/12"
created:
type: string
format: date-time
description: The ISO 8601 date format of the time that this resource was created
example: "2014-12-09T13:50:51.644000Z"
edited:
type: string
format: date-time
description: The ISO 8601 date format of the time that this resource was edited
example: "2014-12-20T21:17:56.891000Z"
url:
type: string
format: uri
description: The hypermedia URL of this resource
example: "https://swapi.info/api/people/1"
required:
- name
- height
- mass
- hair_color
- skin_color
- eye_color
- birth_year
- gender
- homeworld
- films
- species
- vehicles
- starships
- created
- edited
- url
Planet:
type: object
description: A large mass, planet or planetoid in the Star Wars Universe
properties:
name:
type: string
description: The name of this planet
example: "Tatooine"
rotation_period:
type: string
description: The number of standard hours it takes for this planet to complete a single rotation on its axis
example: "23"
orbital_period:
type: string
description: The number of standard days it takes for this planet to complete a single orbit of its local star
example: "304"
diameter:
type: string
description: The diameter of this planet in kilometers
example: "10465"
climate:
type: string
description: The climate of this planet
example: "arid"
gravity:
type: string
description: A number denoting the gravity of this planet, where "1" is normal or 1 standard G
example: "1 standard"
terrain:
type: string
description: The terrain of this planet
example: "desert"
surface_water:
type: string
description: The percentage of the planet surface that is naturally occurring water or bodies of water
example: "1"
population:
type: string
description: The average population of sentient beings inhabiting this planet
example: "200000"
residents:
type: array
description: An array of People URL Resources that live on this planet
items:
type: string
format: uri
example: "https://swapi.info/api/people/1"
films:
type: array
description: An array of Film URL Resources that this planet has appeared in
items:
type: string
format: uri
example: "https://swapi.info/api/films/1"
created:
type: string
format: date-time
description: The ISO 8601 date format of the time that this resource was created
example: "2014-12-09T13:50:49.641000Z"
edited:
type: string
format: date-time
description: The ISO 8601 date format of the time that this resource was edited
example: "2014-12-20T20:58:18.411000Z"
url:
type: string
format: uri
description: The hypermedia URL of this resource
example: "https://swapi.info/api/planets/1"
required:
- name
- rotation_period
- orbital_period
- diameter
- climate
- gravity
- terrain
- surface_water
- population
- residents
- films
- created
- edited
- url
Species:
type: object
description: A type of person or character within the Star Wars Universe
properties:
name:
type: string
description: The name of this species
example: "Human"
classification:
type: string
description: The classification of this species
example: "mammal"
designation:
type: string
description: The designation of this species
example: "sentient"
average_height:
type: string
description: The average height of this species in centimeters
example: "180"
skin_colors:
type: string
description: A comma-separated string of common skin colors for this species
example: "caucasian, black, asian, hispanic"
hair_colors:
type: string
description: A comma-separated string of common hair colors for this species
example: "blonde, brown, black, red"
eye_colors:
type: string
description: A comma-separated string of common eye colors for this species
example: "brown, blue, green, hazel, grey, amber"
average_lifespan:
type: string
description: The average lifespan of this species in years
example: "120"
homeworld:
type: string
format: uri
description: The URL of a planet resource, a planet that this species originates from
example: "https://swapi.info/api/planets/9"
language:
type: string
description: The language commonly spoken by this species
example: "Galactic Basic"
people:
type: array
description: An array of People URL Resources that are a part of this species
items:
type: string
format: uri
example: "https://swapi.info/api/people/66"
films:
type: array
description: An array of Film URL Resources that this species has appeared in
items:
type: string
format: uri
example: "https://swapi.info/api/films/1"
created:
type: string
format: date-time
description: The ISO 8601 date format of the time that this resource was created
example: "2014-12-10T13:52:11.567000Z"
edited:
type: string
format: date-time
description: The ISO 8601 date format of the time that this resource was edited
example: "2014-12-20T21:36:42.136000Z"
url:
type: string
format: uri
description: The hypermedia URL of this resource
example: "https://swapi.info/api/species/1"
required:
- name
- classification
- designation
- average_height
- skin_colors
- hair_colors
- eye_colors
- average_lifespan
- homeworld
- language
- people
- films
- created
- edited
- url
Starship:
type: object
description: A single transport craft that has hyperdrive capability
properties:
name:
type: string
description: The name of this starship
example: "Death Star"
model:
type: string
description: The model or official name of this starship
example: "DS-1 Orbital Battle Station"
manufacturer:
type: string
description: The manufacturer of this starship
example: "Imperial Department of Military Research, Sienar Fleet Systems"
cost_in_credits:
type: string
description: The cost of this starship new, in galactic credits
example: "1000000000000"
length:
type: string
description: The length of this starship in meters
example: "120000"
max_atmosphering_speed:
type: string
description: The maximum speed of this starship in the atmosphere
example: "n/a"
crew:
type: string
description: The number of personnel needed to run or pilot this starship
example: "342,953"
passengers:
type: string
description: The number of non-essential people this starship can transport
example: "843,342"
cargo_capacity:
type: string
description: The maximum number of kilograms that this starship can transport
example: "1000000000000"
consumables:
type: string
description: The maximum length of time that this starship can provide consumables for its entire crew without having to resupply
example: "3 years"
hyperdrive_rating:
type: string
description: The class of this starships hyperdrive
example: "4.0"
MGLT:
type: string
description: The Maximum number of Megalights this starship can travel in a standard hour
example: "10"
starship_class:
type: string
description: The class of this starship
example: "Deep Space Mobile Battlestation"
pilots:
type: array
description: An array of People URL Resources that this starship has been piloted by
items:
type: string
format: uri
example: "https://swapi.info/api/people/1"
films:
type: array
description: An array of Film URL Resources that this starship has appeared in
items:
type: string
format: uri
example: "https://swapi.info/api/films/1"
created:
type: string
format: date-time
description: The ISO 8601 date format of the time that this resource was created
example: "2014-12-10T16:36:50.509000Z"
edited:
type: string
format: date-time
description: The ISO 8601 date format of the time that this resource was edited
example: "2014-12-20T21:26:24.783000Z"
url:
type: string
format: uri
description: The hypermedia URL of this resource
example: "https://swapi.info/api/starships/9"
required:
- name
- model
- manufacturer
- cost_in_credits
- length
- max_atmosphering_speed
- crew
- passengers
- cargo_capacity
- consumables
- hyperdrive_rating
- MGLT
- starship_class
- pilots
- films
- created
- edited
- url
Vehicle:
type: object
description: A single transport craft that does not have hyperdrive capability
properties:
name:
type: string
description: The name of this vehicle
example: "Sand Crawler"
model:
type: string
description: The model or official name of this vehicle
example: "Digger Crawler"
manufacturer:
type: string
description: The manufacturer of this vehicle
example: "Corellia Mining Corporation"
cost_in_credits:
type: string
description: The cost of this vehicle new, in galactic credits
example: "150000"
length:
type: string
description: The length of this vehicle in meters
example: "36.8"
max_atmosphering_speed:
type: string
description: The maximum speed of this vehicle in the atmosphere
example: "30"
crew:
type: string
description: The number of personnel needed to run or pilot this vehicle
example: "46"
passengers:
type: string
description: The number of non-essential people this vehicle can transport
example: "30"
cargo_capacity:
type: string
description: The maximum number of kilograms that this vehicle can transport
example: "50000"
consumables:
type: string
description: The maximum length of time that this vehicle can provide consumables for its entire crew without having to resupply
example: "2 months"
vehicle_class:
type: string
description: The class of this vehicle
example: "wheeled"
pilots:
type: array
description: An array of People URL Resources that this vehicle has been piloted by
items:
type: string
format: uri
example: "https://swapi.info/api/people/1"
films:
type: array
description: An array of Film URL Resources that this vehicle has appeared in
items:
type: string
format: uri
example: "https://swapi.info/api/films/1"
created:
type: string
format: date-time
description: The ISO 8601 date format of the time that this resource was created
example: "2014-12-10T15:36:25.724000Z"
edited:
type: string
format: date-time
description: The ISO 8601 date format of the time that this resource was edited
example: "2014-12-20T21:30:21.661000Z"
url:
type: string
format: uri
description: The hypermedia URL of this resource
example: "https://swapi.info/api/vehicles/4"
required:
- name
- model
- manufacturer
- cost_in_credits
- length
- max_atmosphering_speed
- crew
- passengers
- cargo_capacity
- consumables
- vehicle_class
- pilots
- films
- created
- edited
- url
Error:
type: object
description: Error response
properties:
detail:
type: string
description: A human-readable explanation specific to this occurrence of the problem
example: "Not found"
required:
- detail
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment