openapi.yml

openapi: 3.0.3
info:
  description: OpenAPI specification for the ComicVine API
  version: "1.0"
  title: ComicVine API
externalDocs:
  description: Official Documentation
  url: "https://comicvine.gamespot.com/api/documentation"
servers:
  - url: "https://comicvine.gamespot.com/api"
    description: Official Production server

tags:
  - name: character
    description: Endpoints for a character
  - name: issue
    description: Endpoints for a comic issue
  - name: person
    description: Endpoints for a person
  - name: search
    description: Endpoints for the API search
  - name: volume
    description: Endpoints for a comic volume

paths:
  /character/{id}:
    get:
      summary: Get a particular character
      operationId: get_character
      tags:
        - character
      parameters:
        - $ref: "#/components/parameters/id"
        - $ref: "#/components/parameters/format"
        - $ref: "#/components/parameters/field_list"
      responses:
        "200":
          description: Information about the character
          content:
            application/json:
              schema:
                $ref: "./schemas/Response/EntityResponse.yml"
              # TODO example
              # example:
              #   $ref: "./examples/issue.yml"
            application/xml:
              schema:
                $ref: "./schemas/Response/EntityResponse.yml"
              # TODO example
              # example:
              #   $ref: "./examples/character.yml"
  # TODO
  #  /characters:
  # TODO
  #  /chat:
  # TODO
  #  /chats:
  # TODO
  #  /concept:
  # TODO
  #  /concepts:
  # TODO
  #  /episode:
  # TODO
  #  /episodes:
  /issue/{id}:
    get:
      summary: Get a particular issue
      operationId: get_issue
      tags:
        - issue
      parameters:
        - $ref: "#/components/parameters/id"
        - $ref: "#/components/parameters/format"
        - $ref: "#/components/parameters/field_list"
      responses:
        "200":
          description: Information about the issue
          content:
            application/json:
              schema:
                $ref: "./schemas/Response/EntityResponse.yml"
              example:
                $ref: "./examples/responses/issue.yml"
            application/xml:
              schema:
                $ref: "./schemas/Response/EntityResponse.yml"
              example:
                $ref: "./examples/responses/issue.yml"
  # TODO
  #  /issues:
  # TODO
  #  /location:
  # TODO
  #  /locations:
  # TODO
  #  /movie:
  # TODO
  #  /movies:
  # TODO
  #  /object:
  # TODO
  #  /objects:
  # TODO
  #  /origin:
  # TODO
  #  /origins:
  # TODO
  /person/{id}:
    get:
      summary: Get a particular person
      operationId: get_person
      tags:
        - person
      parameters:
        - $ref: "#/components/parameters/id"
        - $ref: "#/components/parameters/format"
        - $ref: "#/components/parameters/field_list"
      responses:
        "200":
          description: Information about the person
          content:
            application/json:
              schema:
                $ref: "./schemas/Response/EntityResponse.yml"
              example:
                $ref: "./examples/responses/person.yml"
            application/xml:
              schema:
                $ref: "./schemas/Response/EntityResponse.yml"
              example:
                $ref: "./examples/responses/person.yml"
  # TODO
  #  /people:
  # TODO
  #  /power:
  # TODO
  #  /powers:
  # TODO
  #  /promo:
  # TODO
  #  /promos:
  # TODO
  #  /publisher:
  # TODO
  #  /publishers:
  # TODO
  #  /series:
  # TODO
  #  /series_list:
  # TODO
  /search:
    get:
      summary: Search to ComicVine database
      operationId: search
      tags:
        - search
      parameters:
        - $ref: "#/components/parameters/format"
        - $ref: "#/components/parameters/query"
        - $ref: "#/components/parameters/field_list"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
        - $ref: "#/components/parameters/resources"
      responses:
        "200":
          description: Search Results
          content:
            application/json:
              schema:
                $ref: "./schemas/Response/EntitiesResponse.yml"
              example:
                $ref: "./examples/responses/search.yml"
            application/xml:
              schema:
                $ref: "./schemas/Response/EntitiesResponse.yml"
              example:
                $ref: "./examples/responses/search.yml"

  # TODO
  #  /story_arc:
  # TODO
  #  /story_arcs:
  # TODO
  #  /team:
  # TODO
  #  /teams:
  # TODO
  #  /types:
  # TODO
  #  /video:
  # TODO
  #  /videos:
  # TODO
  #  /video_type:
  # TODO
  #  /video_types:
  # TODO
  #  /video_category:
  # TODO
  #  /video_categories:
  # TODO
  /volume/{id}:
    get:
      summary: Get a particular volume
      operationId: get_volume
      tags:
        - volume
      parameters:
        - $ref: "#/components/parameters/id"
        - $ref: "#/components/parameters/format"
        - $ref: "#/components/parameters/field_list"
      responses:
        "200":
          description: Information about the volume
          content:
            application/json:
              schema:
                $ref: "./schemas/Response/EntityResponse.yml"
              example:
                $ref: "./examples/responses/volume.yml"
            application/xml:
              schema:
                $ref: "./schemas/Response/EntityResponse.yml"
              example:
                $ref: "./examples/responses/volume.yml"
  # TODO
  #  /volumes
components:
  parameters:
    field_list:
      $ref: "./parameters/field_list.yml"
    filter:
      $ref: "./parameters/filter.yml"
    format:
      $ref: "./parameters/format.yml"
    id:
      $ref: "./parameters/id.yml"
    limit:
      $ref: "./parameters/limit.yml"
    offset:
      $ref: "./parameters/offset.yml"
    query:
      $ref: "./parameters/query.yml"
    resources:
      $ref: "./parameters/resources.yml"
    sort:
      $ref: "./parameters/sort.yml"
  schemas:
    Character:
      $ref: "./schemas/Character.yml"
    Characters:
      $ref: "./schemas/Characters.yml"
    Issue:
      $ref: "./schemas/Issue.yml"
    Issues:
      $ref: "./schemas/Issues.yml"
    People:
      $ref: "./schemas/People.yml"
    Person:
      $ref: "./schemas/Person.yml"
    Volume:
      $ref: "./schemas/Volume.yml"
    Volumes:
      $ref: "./schemas/Volumes.yml"
  # Authentication Mechanisms
  securitySchemes:
    # Define API Key Authentication
    api_key:
      name: api_key
      type: apiKey
      in: query
      description: |
        # API Key

        Your ComicVine API key, required for access to any of the API's resources.

        You can get your own API Key on the [ComicVine API info page](https://comicvine.gamespot.com/api/).

        ## Format

        It is 40 characters long with containing only lowercase characters along with numbers.

        __example:__ `4ddon0bxepyyb19iz6m54mtucqm83bsj6fn9othx`

        __regex pattern:__ `^[a-z0-9]*$`

# Use API Key Authentication globally
security:
  - api_key: []