How To Use Swagger: Planning For An API.

How To Use Swagger: Planning An API.

1/30/2018

To watch the youtube video where I explain this topic, click here.

So We Want To Make An API...

In the previous blog post, we went over what an API is and and the steps required to make one. As part of a learning process, we're going to be making our very own API, while going through all of the steps involved in making an API.

In this article, we'll be planning what our API does, and creating the Swagger document so that any of our API users know how they can use our API.

What Our API Does

Let's pretend that we run a website that sells fruits. We have a certain number of fruits in our warehouse. Sometimes we get more fruits because shipments come in, and sometimes we sell fruits. We have a website for our customers to buy fruits, and a few in-house applications for our staff to use so that they can report sales and shipments. We'll have a database that stores the number of fruits we have, and we'll create an API to facilitate all of these different software interacting with the database.

So let's define a few things that we want this particular API to do:

We want to be able to add new fruit types to the database.
We want to be able to update fruits that we already have in the database. (Both adding new shipments and subtracting sold fruits.
We also need to be able to tell our websites and staff how many of a particular fruit that we have.

Our API Specifications: Careful Planning

Okay, first of all, assume that we have some form of data persistence. This is most likely a database, with a table with columns for the fruit name and quantity, but could also be in some other form.

Next, our list of APIs will be specified by this table.

It's pretty bare for now, but we're going to be specific about all the details when we create the swagger document.

What Is Swagger?

Swagger is sort of like a markup language. You write the specifications of your API in their particular format (in a yaml file (or json, but the json version isn't as good)), and then you can view your API specification in a very pretty formation.

Anyone who needs to use your API can easily see the available paths, what they need to do to use your API, since examples and documentation is there in a very easily readable format.

(It also makes it easy to code the API later since everything is clearly defined.)

How To Use Swagger

I'm going to be 100% honest here...I never actually remember the exact details of yaml for making a Swagger document. Usually, I just go to the template page for swagger, and overwrite the petstore example with my own API needs.

After a while, you'll remember the syntax and how everything is done, but for now, just look at the syntax of the petstore example and change the methods and names and parameter types as necessary for the API you're making.

Again, go to this webpage and change the things you need: editor.swagger.io/

Our API, Defined In Swagger

This is the swagger code for our project. I looked at the plans that we had before, and made the swagger document for our API's needs.

swagger: "2.0"
info:
  description: "This is an example API for www.srcmake.com. The API pretends that we have a fruit store with some quantity of each fruit. We need to allow for the updates of each fruit as we get more in stock or sell some, as well as be able to check for the number of fruits that we have."
  version: "1.0.0"
  title: "srcFruitsAPI"
  termsOfService: "http://www.srcmake.com/"
  contact:
    email: "example@gmail.com"
  license:
    name: "srcLicense"
    url: "http://www.srcmake.com"
host: "srcmake.com"
basePath: "/v1"
tags:
- name: "Updating"
  description: "These APIs update the fruit quantities."
- name: "Getting"
  description: "These APIs return the quantities of fruits."
schemes:
- "http"
paths:
  /add:
    post:
      tags:
      - "Updating"
      summary: "Add some fruits to our inventory."
      description: "Enter the fruit name and quantity and that amount will be added to that fruit's inventory count."
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "fruitname"
        in: "query"
        required: true
        description: "The name of the fruit."
        type: "string"
      - name: "quantity"
        in: "query"
        required: true
        description: "The amount of this fruit."
        type: "string"
      responses:
        200:
          description: "OK."
          schema:
            $ref: "#/definitions/Success"
        400:
          description: "Bad input information."
        500:
          description: "Internal server error."
  /subtract:
    post:
      tags:
      - "Updating"
      summary: "Remove some fruits from our inventory."
      description: "Enter the fruit name and quantity and that amount will be subtracted from that fruit's inventory count."
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "fruitname"
        in: "query"
        required: true
        description: "The name of the fruit."
        type: "string"
      - name: "quantity"
        in: "query"
        required: true
        description: "The amount of this fruit."
        type: "string"
      responses:
        200:
          description: "OK."
          schema:
            $ref: "#/definitions/Success"
        400:
          description: "Bad input information."
        500:
          description: "Internal server error."
          
  /check:
    get:
      tags:
        - "Getting"
      summary: "Check the quantity of a fruit."
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "fruitname"
        in: "query"
        required: true
        description: "The name of the fruit."
        type: "string"
      responses:
        200:
          description: "OK."
          schema:
            $ref: "#/definitions/Quantity"
        400:
          description: "Bad input information."
        500:
          description: "Internal server error."
        

  
definitions:
  Quantity:
    properties:
      fruitname:
        type: "string"
      quantity:
        type: "integer"
    
  Success:
    properties:
      status:
        type: "string"
        enum: ["Success", "Failure"]
        description: "Success or Failure."

Does it seem complicated? It's not. Watch the video and I'll go over what everything means.

Copy and paste the code into the swagger editor to see it in it's full glory.

What's Next?

Well, so far we're learned about APIs, we planned one out, and even made the swagger document for it. Next up is...coding!

I'm going to be coding this in both Java and NodeJS, so make sure to go to the appropriate article for the language you prefer.

To see this API coded in Java, click here.
To see this API coded in NodeJS, click here.

Here's the youtube video where I go over the above code:

Like this content and want more? Feel free to look around and find another blog post that interests you. You can also contact me through one of the various social media channels.

Twitter: @srcmake
Discord: srcmake#3644
Youtube: srcmake
Twitch: www.twitch.tv/srcmake
Github: srcmake

Comments are closed.

Author

Hi, I'm srcmake. I play video games and develop software.

Pro-tip: Click the "DIRECTORY" button in the menu to find a list of blog posts.

License: All code and instructions are provided under the MIT License.

Discord

Chat with me.

Youtube

Watch my videos.

Twitter

Get the latest news.

Twitch

See the me code live.

Github

My latest projects.