openapi: 3.1.0
info:
  title: Scalar Galaxy
  description: |
    The Scalar Galaxy is an example OpenAPI specification to test OpenAPI tools and libraries. It’s a fictional universe with fictional planets and fictional data. Get all the data for all planets.

    ## Resources

    * https://github.com/scalar/scalar
    * https://github.com/OAI/OpenAPI-Specification
    * https://scalar.com

    ## Markdown Support

    All descriptions *can* contain ~~tons of text~~ **Markdown**. [If GitHub supports the syntax](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax), chances are we’re supporting it, too.

    <details>
      <summary>Examples</summary>

      **Blockquotes**

      > I love OpenAPI. <3

      **Tables**

      | Feature          | Availability |
      | ---------------- | ------------ |
      | Markdown Support | ✓            |

      **Accordion**

      ```html
      <details>
        <summary>Using Details Tags</summary>
        <p>HTML Example</p>
      </details>
      ```

      **Images**

      Yes, there’s support for images, too!

      ![Empty placeholder image showing the width/height](https://images.placeholders.dev/?width=1280&height=720)

    </details>
  version: 1.0.0
  contact:
    name: Marc from Scalar
    url: https://scalar.com
    email: marc@scalar.com
servers:
  - url: https://galaxy.scalar.com
  - url: http://localhost
security:
  - bearerAuth: []
  - basicAuth: []
  - apiKeyQuery: []
  - apiKeyHeader: []
  - apiKeyCookie: []
  - oauth2: []
tags:
  - name: Authentication
    description: Some endpoints are public, but some require authentication. We
      provide all the required endpoints to create an account and authorize
      yourself.
  - name: Planets
    description: Everything about planets
paths:
  /planets:
    get:
      tags:
        - Planets
      summary: Get all planets
      description: It’s easy to say you know them all, but do you really? Retrieve all
        the planets and check whether you missed one.
      operationId: getAllData
      security:
        - {}
      parameters:
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/Planet"
                  - $ref: "#/components/schemas/PaginatedResource"
    post:
      tags:
        - Planets
      summary: Create a planet
      description: Time to play god and create a new planet. What do you think? Ah,
        don’t think too much. What could go wrong anyway?
      operationId: createPlanet
      requestBody:
        description: Planet
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Planet"
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Planet"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/responses/BadRequest"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/responses/Forbidden"
  /planets/{planetId}:
    get:
      tags:
        - Planets
      summary: Get a planet
      description: You’ll better learn a little bit more about the planets. It might
        come in handy once space travel is available for everyone.
      operationId: getPlanet
      security:
        - {}
      parameters:
        - $ref: "#/components/parameters/planetId"
      responses:
        "200":
          description: Planet Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Planet"
        "404":
          description: Planet Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/responses/NotFound"
    put:
      tags:
        - Planets
      summary: Update a planet
      description: Sometimes you make mistakes, that’s fine. No worries, you can
        update all planets.
      operationId: updatePlanet
      requestBody:
        description: New information about the planet
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Planet"
      parameters:
        - $ref: "#/components/parameters/planetId"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Planet"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/responses/BadRequest"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/responses/Forbidden"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/responses/NotFound"
    delete:
      tags:
        - Planets
      summary: Delete a planet
      operationId: deletePlanet
      description: This endpoint was used to delete planets. Unfortunately, that
        caused a lot of trouble for planets with life. So, this endpoint is now
        deprecated and should not be used anymore.
      deprecated: true
      parameters:
        - $ref: "#/components/parameters/planetId"
      responses:
        "204":
          description: No Content
        "404":
          description: Not Found
  /planets/{planetId}/image:
    post:
      tags:
        - Planets
      summary: Upload an image to a planet
      description: Got a crazy good photo of a planet? Share it with the world!
      operationId: uploadImage
      parameters:
        - $ref: "#/components/parameters/planetId"
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  format: binary
      responses:
        "200":
          description: Image uploaded
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Image uploaded successfully
        "400":
          description: Bad Upload Request
          content:
            application/json:
              schema:
                $ref: "#/components/responses/BadRequest"
        "403":
          description: Upload Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/responses/Forbidden"
        "404":
          description: Failed to Upload Image, Planet Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/responses/NotFound"
  /user/signup:
    post:
      tags:
        - Authentication
      summary: Create a user
      description: Time to create a user account, eh?
      operationId: createUser
      security:
        - {}
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewUser"
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/responses/BadRequest"
  /auth/token:
    post:
      tags:
        - Authentication
      summary: Get a token
      description: Yeah, this is the boring security stuff. Just get your super secret
        token and move on.
      operationId: getToken
      security:
        - {}
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Credentials"
      responses:
        "201":
          description: Token Created
          content:
            application/json:
              schema:
                ref: "#/components/schemas/Token"
  /me:
    get:
      tags:
        - Authentication
      summary: Get authenticated user
      description: Find yourself they say. That’s what you can do here.
      operationId: getMe
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/responses/Forbidden"
webhooks:
  newPlanet:
    post:
      tags:
        - Planets
      requestBody:
        description: Information about a new planet
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Planet"
      responses:
        "200":
          description: Return a 200 status to indicate that the data was received
            successfully
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    basicAuth:
      type: http
      scheme: basic
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    apiKeyQuery:
      type: apiKey
      in: query
      name: api_key
    apiKeyCookie:
      type: apiKey
      in: cookie
      name: api_key
    oauth2:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://galaxy.scalar.com/oauth/authorize
          scopes:
            write:planets: modify planets in your account
            read:planets: read your planets
  parameters:
    planetId:
      name: planetId
      in: path
      required: true
      schema:
        type: integer
        format: int64
        examples:
          - 1
    limit:
      name: limit
      in: query
      description: The number of items to return
      required: false
      schema:
        type: integer
        format: int64
        default: 10
    offset:
      name: offset
      in: query
      description: The number of items to skip before starting to collect the result set
      required: false
      schema:
        type: integer
        format: int64
        default: 0
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFound:
      description: NotFound
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  schemas:
    NewUser:
      type: object
      required:
        - name
        - email
        - password
      properties:
        name:
          type: string
          examples:
            - Marc
        email:
          type: string
          format: email
          examples:
            - marc@scalar.com
        password:
          type: string
          minLength: 8
          examples:
            - i-love-scalar
    User:
      type: object
      required:
        - id
        - name
        - email
      properties:
        id:
          type: integer
          format: int64
          examples:
            - 1
        name:
          type: string
          examples:
            - Marc
        email:
          type: string
          format: email
          examples:
            - marc@scalar.com
    Credentials:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
          examples:
            - marc@scalar.com
        password:
          type: string
          examples:
            - i-love-scalar
    Token:
      type: object
      properties:
        token:
          type: string
          examples:
            - eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
    Planet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
          examples:
            - 1
          x-variable: planetId
        name:
          type: string
          examples:
            - Mars
        description:
          type:
            - string
            - "null"
          examples:
            - The red planet
        image:
          type: string
          nullable: true
          examples:
            - https://cdn.scalar.com/photos/mars.jpg
        creator:
          $ref: "#/components/schemas/User"
    PaginatedResource:
      type: object
      properties:
        meta:
          type: object
          properties:
            limit:
              type: integer
              format: int64
              examples:
                - 10
            offset:
              type: integer
              format: int64
              examples:
                - 0
            total:
              type: integer
              format: int64
              examples:
                - 100
            next:
              type:
                - string
                - "null"
              examples:
                - /planets?limit=10&offset=10
    Error:
      type: object
      description: RFC 7807 (https://datatracker.ietf.org/doc/html/rfc7807)
      properties:
        type:
          type: string
          examples:
            - https://example.com/errors/generic-error
        title:
          type: string
          examples:
            - Something went wrong here.
        status:
          type: integer
          format: int64
          examples:
            - 403
        detail:
          type: string
          examples:
            - Unfortunately, we can’t provide further information.