OAS v3 example using DeckofCardsAPI.com

openapi.yaml

openapi: 3.0.0
info:
  title: Deck of Cards API
  description: |
    An API to simulate a deck of cards. This API can be used to build card games of all types. New decks may be created using a single deck of 52 cards, or multiple decks may be used to create a large deck of cards. 
    
    This API supports the following capabilities - 
    
    * Create a new deck, shuffled or unshuffled (order preserved)
    * Reshuffle an existing deck
    * Draw one or more cards from an existing deck
    * Create piles of cards that can receive a draw
    * Create a new deck with a specific set of cards
    
    The API offers images of each card for easy display. 
    
  contact: {}
  version: '1.0'
servers:
- url: https://www.deckofcardsapi.com/api/
  variables: {}
paths:
  "/deck/new/":
    post:
      summary: Create a Shuffled Deck
      operationId: NewShuffledDeck
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeckDetails"
      security: []
  "/deck/{deck_id}/draw/":
    post:
      summary: Draw a new card from an existing deck
      operationId: DrawCard
      parameters:
      - name: deck_id
        in: path
        description: |
          The Deck ID to shuffle. 
        required: true
        schema:
          type: string
          example: "8obqzdtk9tau"
      - name: count
        in: query
        description: 'The number of cards to draw. Defaults to 1 if not specified'
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
          default: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array 
                items:
                  $ref: "#/components/schemas/CardDraw"
  "/deck/{deck_id}/shuffle/":
    post:
      summary: Reshuffle an existing deck
      operationId: ReshuffleDeck
      parameters:
      - name: deck_id
        in: path
        description: |
          The Deck ID to shuffle. 
        required: true
        schema:
          type: string
          example: "8obqzdtk9tau"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeckDetails"
      security: []
components:
  schemas:
    CardDraw:
      type: object
      description: |
        Represents a card that was drawn from a deck
      properties:
        code:
          type: string
          description: "A code that represents the card drawn. (e.g. KH means the King of Hearts)"
        image:
          type: string
          description: "The absolute URL to the PNG image of the card drawn"
        images:
          type: object
          description: "Contains multiple image formats for rendering the drawn card"
          properties:
            svg:
              type: string
              description: "The absolute URL to the vectorized image (SVG) of the card drawn"
            png:
              type: string
              description: "The absolute URL to the PNG image of the card drawn"                    
          example:
            svg: https://deckofcardsapi.com/static/img/KH.svg
            png: https://deckofcardsapi.com/static/img/KH.png
        value:
          type: string
          description: "A string representing the card value as a numeric value or face value (e.g. KING)"
        suit:
          type: string
          description: "A string representing the suit of the card (e.g. HEARTS)"
    DeckDetails:
      type: object
      description: |
        Represents the current state of a deck, including if it was shuffled, the number of cards still remaining to be drawn before the deck has been exhausted
      properties:
        success:
          type: boolean
          description: "True if the request was successful"
        deck_id:
          type: string
          description: "The deck identifier, as provided in the request path"
        remaining:
          type: integer
          format: int32
          description: "The number of cards available for drawing"
        shuffled:
          type: boolean
          description: "True if the deck is shuffled"
      example:
        success: true
        deck_id: "8obqzdtk9tau"
        remaining: 52
        shuffled: true
        
tags: []