Blog API Swagger definition

blog.yml

swagger: "2.0"
info:
  description: "This is a blog API defined in swagger"
  version: "1.0.0"
  title: "Swagger blog API"
  termsOfService: "http://blog.dukic.co.nz/terms"
  contact:
    email: "[email protected]"
  license:
    name: "AGPL 3.0"
    url: "https://www.gnu.org/licenses/agpl-3.0.en.html"
host: "blog.dukic.co.nz"
basePath: "/v1"
tags:
- name: "blogpost"
  description: "Blog post talking about whatever you want to talk about"
  externalDocs:
    description: "Find out more"
    url: "https://en.wikipedia.org/wiki/Blog"
- name: "author"
  description: "The person that wrote the blog post"
schemes:
- "https"
- "http"
paths:
  /blogpost:
    get:
      tags:
      - "blogpost"
      summary: "Get list of all blogposts"
      description: ""
      operationId: "getBlogPosts"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "query"
        name: "author"
        description: "The author of the blogposts to retrieve"
        required: false
        type: "string"
      - name: "page"
        in: "query"
        description: "Page number of results to return."
        required: false
        type: "string"
      responses:
        200:
          description: "Successful operation"
          schema:
            $ref: "#/definitions/BlogPosts"
    post:
      tags:
      - "blogpost"
      summary: "Add a new blogpost to the site"
      description: ""
      operationId: "addBlogPost"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "content"
        name: "content"
        description: "BlogPost object that needs to be added to the site"
        required: true
        schema:
          $ref: "#/definitions/BlogPost"
      responses:
        405:
          description: "Invalid input"
        201:
          description: "Created successfully"
          schema:
            $ref: "#/definitions/BlogPost"
    put:
      tags:
      - "blogpost"
      summary: "Update an existing blogpost"
      description: ""
      operationId: "updateBlogPost"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "content"
        name: "content"
        description: "BlogPost object that needs to be updated on the site"
        required: true
        schema:
          $ref: "#/definitions/BlogPost"
      responses:
        400:
          description: "Invalid ID supplied"
        404:
          description: "BlogPost not found"
        405:
          description: "Validation exception"
        200:
          description: "Updated successfully"
          schema:
            $ref: "#/definitions/BlogPost"
definitions:
  BlogPost:
    type: "object"
    required:
    - "title"
    - "content"
    - "author"
    properties:
      id:
        type: "integer"
        format: "int64"
      title:
        type: "string"
        example: "How to be a successful blogger"
      content:
        type: "string"
        example: "This article talks about how to be a success at writing things online. In this article ..."
      author:
        $ref: "#/definitions/Author"
  BlogPosts:
    type: "array"
    items:
      $ref: "#/definitions/BlogPosts"
  Author:
    type: "object"
    required:
    - "firstname"
    properties:
      id:
        type: "integer"
        format: "int64"
      first_name:
        type: "string"
        example: "Bob"
      last_name:
        type: "string"
        example: "Smith"
externalDocs:
  description: "Find out more about Books"
  url: "http://books.example.io"