openapi_example.yml

---
openapi: 3.0.0
servers:
- description: JokeAPI server example
  url: https://joke_api.example.com/
info:
  description: |
    This simple Joke API allows you to publish joke and vote for you favourite!
  version: 1.1.0
  title: Simple Joke API
  contact:
    email: you@your-company.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
tags:
- name: admins
  description: Secured Admin-only calls
- name: developers
  description: Operations available to regular developers
paths:
  "/joke":
    get:
      tags:
      - developers
      summary: searches jokes
      operationId: searchJokes
      description: |
        By passing in the appropriate options, you can search for
        available jokes
      parameters:
      - in: query
        name: searchString
        description: pass an optional search string for looking up inventory
        required: false
        schema:
          type: string
      - in: query
        name: numberofJokes
        description: number of jokes to return
        schema:
          type: integer
          format: int32
          minimum: 1
          default: 25
      - in: query
        name: category
        description: category of jokes to return
        example: knockKnock
        required: false
        schema:
          type: string
          enum:
            - Word game
            - Classic
            - School
            - KnockKnock
      - in: query
        name: sortBy
        example: thumbsUp
        required: false
        schema:
          type: string
          enum:
            - thumbsUp
            - thumbsDown
            - dateAdded
      - name: sortOrder
        in: query
        description: "asc is ascending and sorts from A to Z.
          desc is descending and sorts from Z to A."
        example: desc
        required: false
        schema:
          type: string
          enum:
            - asc
            - desc
      responses:
        '200':
          description: search results matching criteria
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Joke"
              examples:
                Homework:
                  $ref: "#/components/examples/Homework"
                OpenTheDoor:
                  $ref: "#/components/examples/OpenTheDoor"
        '400':
          description: bad input parameter
    post:
      tags:
      - admins
      summary: adds a joke
      operationId: addJoke
      description: Adds a joke to the system
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/JokeWithPunchline"
                - $ref: "#/components/schemas/Pun"
              type: object
              required:
              - joke
              - punchline
              properties:
                joke:
                  type: string
                  example: Knock Knock. Who's there? Hike. Hike Who?
                  description: The joke
                punchline:
                  example: I didn't know you liked Japanese poetry.
                  description: The punchline.
                  type: string
                category:
                  example: knockKnock
                  description: category of the joke (allowed categories TBD)
                  type: string
      responses:
        '201':
          description: item created
          content:
            application/vnd.json:
              schema:
                "$ref": "#/components/schemas/Joke"
              examples:
                SmartDog:
                  $ref: "#/components/examples/SmartDog"
                OpenTheDoor:
                  $ref: "#/components/examples/OpenTheDoor"
        '400':
          description: invalid input, object invalid
        '409':
          description: an existing item already exists
  "/thumbsUp/{id}":
    post:
      tags:
      - developers
      summary: thumbsup  a joke
      operationId: Thumbs up to a joke
      description: Increases Thumbs up count of a joke by one.
      parameters:
      - name: id
        example: ce0b9fbe-7ad8-11eb-9439-0242ac130002
        description: The joke ID for the joke you want to thumbsup.
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Thumbs Up added
  "/thumbsDown/{id}":
    post:
      tags:
      - developers
      summary: thumbsdown a joke
      operationId: Thumbs down to a joke
      description: Increases Thumbs down count of a joke by one.
      parameters:
      - name: id
        example: ce0b9fbe-7ad8-11eb-9439-0242ac130002
        description: The joke ID for the joke you want to thumbsdown.
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Thumbs down added

components:
  schemas:
    Joke:
      type: object
      required:
      - id
      - dateAdded
      - joke
      - punchline
      - thumbsUp
      - thumbsDown
      - category
      properties:
        id:
          type: string
          description: The id of the Joke. Assigned when added.
        joke:
          type: string
          description: The lead-in to the joke.
        punchline:
          type: string
          description: This bit should make you laugh :).
        category:
          type: string
          description: the category of the joke.
          enum:
            - Word game
            - Classic
            - School
            - KnockKnock
            - French humour
        thumbsUp:
          type: integer
          description: Count of upvotes for the joke.
        thumbsDown:
          type: integer
          description: Count of down votes for the joke.
        dateAdded:
          type: string
          format: date-time
    JokeWithPunchline:
      title: Joke with punchline
      type: object
      required:
      - joke
      example:
        joke: Knock Knock. Who's there? Hike. Hike Who?
        punchline: I didn't know you liked Japanese poetry.
        category: KnockKnock
      properties:
        joke:
          type: string
          description: The joke
        punchline:
          description: The punchline.
          type: string
        category:
          description: category of the joke
          type: string
          enum:
            - Word game
            - Classic
            - School
            - KnockKnock
    Pun:
      type: object
      required:
      - joke
      properties:
        joke:
          type: string
          description: The pun, single sentence
        category:
          description: category of the joke
          type: string
          enum:
            - Word game
            - Classic
            - School
            - KnockKnock
      example:
        joke: He had a photographic memory but never developed it.
        category: Word game
  examples:
    Homework:
      summary: Well done, son
      value:
        - id: 42
          joke: "Teacher: Did your father help you with your homework?"
          punchline: "Student: No, he did it all by himself."
          category: School
          dateAdded: '2015-07-12T20:12:33.001Z'
          thumbsUp: 6
          thumbsDown: 2
    OpenTheDoor:
      summary: Open your mind
      value:
        - id: 42
          joke: What is the name to open the door?
          punchline: Open your chakra
          category: Classic
          dateAdded: '1998-07-12T20:12:33.001Z'
          thumbsUp: 4
          thumbsDown: 2
    SmartDog:
      summary: Long way top school
      value:
        - id: 33
          joke: "He used to take his dog to school every day, but he finally had to stop. How come?"
          punchline: "The dog got graduated."
          category: School
          dateAdded: '2017-07-12T20:12:33.001Z'
          thumbsUp: 3
          thumbsDown: 3