<div class="post-toc-block float-default with-border"> 
						<div class="post-toc-header">Table of Contents</div>
						<nav id="md-post-toc" class="md-post-toc"></nav>
						</div>Hello folks, let&#8217;s learn something new today. Some of you might have stumbled onto this blog and some might have heard about Swagger and would be wanting to know more. In either case I promise, after reading this blog, you would have increased your knowledge about swagger beginners guide and how it can help you create and document your APIs.
<blockquote>What is Swagger? How does Swagger help in making and documenting APIs and what other things can it do? How do I write a Swagger API as a beginner? Is OpenAI specification different from Swagger specification? What is API schema and how to make one using Swagger? Let&#8217;s get to the answers, now!</blockquote>
Swagger is an Open-Source API documentation framework. It is used for documenting REST APIs. It provides HTML view of the API documentation with JSON support and detailed information on the HTTP methods. 
Swagger documentation helps frontend developers and other users of the API know what are the endpoints, what data needs to be passed, which methods can be used, if authentication is required or not, if there are any other necessary/optional parameters to the endpoint. Developers get to know what the API is all about and hence it becomes easier to understand and test the <a href="https://keploy.io/blog/community/an-introduction-to-api-testing">API</a> they are working with.
<blockquote>The OpenAPI Specification, formerly known as the Swagger Specification, is the world’s standard for defining RESTful interfaces. The OAS enables developers to design a technology-agnostic API interface that forms the basis of their API development and consumption.</blockquote>
Swagger API was created by Tony Tam in 2011. In 2015 a new organization named Open AI initiative was formed and in 2016 Swagger specification was given a new name of OpenAPI specification. Swagger consists of the tools provided by the SmartBear company and OpenAPI refers to the API specification defined and maintained by the Open API initiative. 
The <a href="https://editor.swagger.io/">Swagger Editor</a> is an easy way to get started with the OpenAPI Specification to design, describe and document our API. The official docs for Swagger beginners guide Editor is linked <a href="https://support.smartbear.com/swaggerhub/docs/tutorials/openapi-3-tutorial.html">here</a>, in case you want to have a detailed look. But for now, let&#8217;s create a simple API with OpenAPI specification.
On your right is the Swagger UI tool and on the left is the space where we&#8217;ll be writing some code. Let&#8217;s dive right in&#8230;.
<img decoding="async" src="https://cdn.hashnode.com/res/hashnode/image/upload/v1657781885195/tSIp_FYrC.png" alt="1.png" />
Here, we first specify the version of OpenAI that we are using. Then under info, we specify the title of our API, a short description of it&#8217;s functionality, a contact to know more about the API and also what is the version of our API that we&#8217;re currently building. We also specify the servers our API can be accessed from and by. Ofcourse, I&#8217;ve specified just dummy servers for now.
Now we specify the paths, where we add resource and the operations as well. So we add description to the path and first add the GET operation, for which we specify it&#8217;s description, parameters and responses. So we choose that it&#8217;s going to be a query parameter, give it a name and specify that this is required. In the schema, we specify the type of the parameter and give a sample example.
<img decoding="async" src="https://cdn-images-1.medium.com/max/1320/1*wWsJiYpgrKDevuHIDRiemA.png" alt="get1.png" />
In the responses, we add a simple 200 response that implies a Successful response. Then, we define the content to be JSON and add schema of the response. There are two ways to define the schema or the details of the payload, one is to define it within the operation and the other is to make separate components and then refer it in the operation. The second way is better since it&#8217;s more reusable and we will learn about it towards the end of this blog. For now let&#8217;s go ahead with the first way and specify type as array since we&#8217;re expecting an array of employees. We also need to define the properties of each item, which in our case includes EmployeeID, EmployeeName and EmployeeGender. We specify the type of each property and also provide an accompanying example.
<img decoding="async" src="https://cdn-images-1.medium.com/max/1320/1*M3B_7Aq8pvrC4lFTY38UOQ.png" alt="get2.png" />
Great, now we can see on the right the GET operation is expecting Employee Name. Now that we have our GET operation in place, let&#8217;s write our POST operation too. For this we add a description, the request body and the responses as well.
<img decoding="async" src="https://cdn-images-1.medium.com/max/1320/1*JG06chsbJzzfR8w2CpHSOg.png" alt="post1.png" />
The request body will have the content specified as JSON and the schema will have same properties like what we defined for our GET operation but here the type will be object since we would send only one employee record data to be added.
<img decoding="async" src="https://cdn-images-1.medium.com/max/1320/1*urqnqSe8j328eK2gb8m9rw.png" alt="post2.png" />
We add 201 under responses which indicates that the request was successful and the employee name has been added. Wuhoo, on the right you can see the POST operation is expecting a JSON as a request body. We are getting our employee resource as a query parameter but what if we want to get it as a path parameter.
<img decoding="async" src="https://cdn-images-1.medium.com/max/1320/1*DAZDIZooOK4gRx15el8AAA.png" alt="getp1.png" />
Here, we retrieve the employee through the Path parameter. In this GET operation we include the parameters and responses like we did in our GET operation earlier in the Query Parameter. The only difference here would be under the parameters&#8217; &quot;in&quot; we would specify &quot;path&quot; instead of &quot;query&quot; like we did earlier.
<img decoding="async" src="https://cdn-images-1.medium.com/max/1320/1*EAgPdoy_VVISsb-YoBkLqQ.png" alt="getp2.png" />
Amazing, our API is complete now. We can see employee GET operation with PATH parameter expecting Employee id. Now our API is complete but we can do some optimizations by using API schemas instead of writing request and response schemas repeatedly. API schemas help developers interact with an API and it&#8217;s standardization helps in automating the integration process.
<img decoding="async" src="https://cdn-images-1.medium.com/max/1320/1*vIRA8_uDo1vsd_D-9otUmA.png" alt="schemas.png" />
So in our root level we write our components, under which we define the two type of schemas a single employee object and an array of employees. After writing the type, just copy-paste the properties from above for each schema. We have defined two schemas inside our components. If you hover over the yellow error on the left side, you&#8217;ll see it says &quot;Definition was declared but never used in this document&quot;. This is because we&#8217;ve created schemas but have never referenced them in our code above. Let&#8217;s do that now!
<img decoding="async" src="https://cdn-images-1.medium.com/max/1320/1*jkrZYNjsH0jUlmIQHrx3dQ.png" alt="get.png" />
Now going on to the Employee Resource GET operation, we can remove the part under schema highlighted in the picture above and instead use &quot;$ref&quot; to provide it the reference path of employees schema.
<pre><code class="language-go">$ref: '#/components/schemas/employees'</code></pre>
<img decoding="async" src="https://cdn-images-1.medium.com/max/1320/1*IMnQG5VrBgx3e3iUC_wgOw.png" alt="post.png" />
Similarly, go to the Employee Resource POST operation, and under schema use &quot;$ref&quot; to provide it the reference path of employee schema.
<pre><code class="language-go">$ref: '#/components/schemas/employee'</code></pre>
<img decoding="async" src="https://cdn-images-1.medium.com/max/1320/1*B4IH29jtI5tEOZOTH1OXFQ.png" alt="getp.png" />
Similarly, go to the Path parameter Employee Resource GET operation, and under schema use &quot;$ref&quot; to provide it the reference path of employees schema.
<pre><code class="language-go">$ref: '#/components/schemas/employees'</code></pre>
<img decoding="async" src="https://cdn-images-1.medium.com/max/1320/1*e1ffuZU9AwJXPDF33hs4Tg.png" alt="final.png" />
Now all of our operations are referring to the required schema of our API and we have successfully reduced code repetition. We can now see that the documentation on the right in the Swagger UI tool is very helpful to understand our API and it&#8217;s methods in it&#8217;s entirety. Voila&#8230; your API created and documented on Swagger is ready to be shown to the world now!
For any feedback or doubts, please feel free to comment below. Happy Learning! 🙂

 
 
 

 
 <div class="pp-multiple-authors-boxes-wrapper pp-multiple-authors-wrapper pp-multiple-authors-layout-boxed multiple-authors-target-the-content box-post-id-16 box-instance-id-1 ppma_boxes_16"
 data-post_id="16"
 data-instance_id="1"
 data-additional_class="pp-multiple-authors-layout-boxed.multiple-authors-target-the-content"
 data-original_class="pp-multiple-authors-boxes-wrapper pp-multiple-authors-wrapper box-post-id-16 box-instance-id-1">
 <h2 class="widget-title box-header-title">Author</h2>
 
 <div class="ppma-author-category-wrap">
 
 <ul class="pp-multiple-authors-boxes-ul">
 <li class="pp-multiple-authors-boxes-li author_index_0 author_sejal-jain has-avatar">
 <div class="pp-author-boxes-avatar">
 <img alt='Sejal Jain' src='https://wp.keploy.io/wp-content/uploads/2024/10/sejal-jain.jpg' srcset='https://wp.keploy.io/wp-content/uploads/2024/10/sejal-jain.jpg' class='multiple_authors_guest_author_avatar avatar' height='80' width='80'/> </div>
 
 <div class="pp-author-boxes-avatar-details">
 <div class="pp-author-boxes-name multiple-authors-name">
 <a href="https://wp.keploy.io/author/sejal-jain/" rel="author" title="Sejal Jain" class="author url fn">Sejal Jain</a> 
 </div>
 
 I'm a 2023 Computer Science Engineering graduate from GGSIPU and a full-time employee at Zomato. She has interned at Zomato, A.P. Moller - Maersk, and Keploy, and a Women Engineers Fellow and Generation Google 2021 APAC Scholar, currently learning React.js. 
 <a class="ppma-author-user_url-profile-data ppma-author-field-meta ppma-author-field-type-url" aria-label="Website" href="https://www.linkedin.com/in/sejal-jain17/" rel="dofollow" target="_blank"> </a>
 
 </div>
 </li>
 </ul>
 
 </div>
 
 </div>
 
 
 
 <style>
 .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .pp-author-boxes-avatar img { width: 80px !important; height: 80px !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .pp-author-boxes-avatar img { border-style: none !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .pp-author-boxes-avatar img { border-radius: 50% !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .pp-author-boxes-meta a { background-color: #655997 !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .pp-author-boxes-meta a { color: #ffffff !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .pp-author-boxes-meta a:hover { color: #ffffff !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .ppma-author-user_email-profile-data { background-color: #655997 !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .ppma-author-user_email-profile-data { border-radius: 100% !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .ppma-author-user_email-profile-data { color: #ffffff !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .ppma-author-user_url-profile-data { background-color: #655997 !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .ppma-author-user_url-profile-data { border-radius: 100% !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .ppma-author-user_url-profile-data { color: #ffffff !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .pp-author-boxes-recent-posts-title { border-bottom-style: dotted !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .pp-multiple-authors-boxes-li { border-style: solid !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .pp-multiple-authors-boxes-li { border-width: 1px !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .pp-multiple-authors-boxes-li { border-color: #999 !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .pp-multiple-authors-boxes-li { color: #3c434a !important; } </style>

Swagger beginners guide – Design and Document your APIs

Gemini 2.5 Pro vs OpenAI o1: Benchmarking AI Models for Software Testing

Smoke Testing vs Regression Testing: What You Need to Know

Agile Testing Best Practices for Faster, Higher‑Quality Releases

Introduction to REST API in Python

A Technical Guide to Test Mock Data: Levels, Tools, and Best Practices

Maintaining Auto-Generative API Tests: Need of de-duplicate tests

Integration of E2E Testing in a CI/CD Pipeline

Building Keploy.io, an EBPF based open source framework to generate test cases and data stubs from API calls.

Neha Gupta

Cloud technology veteran and probably the youngest (globally) to have completed all 5 AWS certifications (including Solutions architect Professional and Dev­ops engineer professional)

Swagger Beginners Guide – Design And Document Your Apis

More Stories