Swagger Spotlight: Generating OAS, Testing with Swagger UI, and More

This week’s edition of Swagger Spotlight is a roundup of fresh content from around the web from individuals that are building APIs with the OpenAPI Specification and Swagger tools.
Swagger Spotlight: Generating OAS, Testing with Swagger UI, and More

This week’s edition of Swagger Spotlight is a roundup of fresh content from around the web from individuals that are building APIs with the OpenAPI Specification and Swagger tools. We’ve hand selected this week’s articles but are also accepting submissions for the next Swagger Spotlight to be featured on the Swagger Blog. If you’d like to write a Swagger Spotlight feature piece, check out what we are looking for here and submit your topic today. If you’re looking to build awareness around projects you’re working on, or just share some knowledge you have surrounding Swagger tools, we want to hear from you!

ICYMI – Last Week’s Swagger Spotlight Feature:

Automatically Generate OpenAPI Specifications & Documentation with Python

In this article, Thomas Pollet walks you through how to use his project on GitHub to automatically generate OAS specifications and Swagger UI documentation with Python. He has created an open source python-pip package: safrs. safrs is an acronym that stands for the main technologies used: SqlAlchemy, Flask-Restful & Swagger. He discusses how the purpose of this framework is to help python developers create a self-documenting JSON API for sqlalchemy database objects and relationships.


The first time I was introduced to Swagger was a couple of years ago when I had to implement a system monitoring app using the nutanix REST API. I found it to be a really convenient way to debug and document web services. Later, when asked to provide documentation for a different project, I went back to Swagger (now OpenAPI) and implemented the specification.

Like most of today’s webservices, the API endpoints for this project provided CRUD functionality: create, read, update, delete operations to a database backend. A lot of the information that needed to be described in the specification was already implicitly coded into the application, so instead of manually writing down the spec, I decided to generate it using the available application semantics.

Read More

How to Use Swagger UI for API Testing

This article walks the reader through how to user Swagger UI for API testing. It starts by getting into the basics of Swagger UI, why it’s a great tool to use, and then moves in to the tutorial on how to test your APIs with it. Very useful for people looking to do some manual testing within Swagger UI. This tutorial is easy to follow along with, and straight forward. You can follow along with the example used (http://petstore.swagger.io/v2/swagger.json), or try this out with your own URL.


In this article I will show you how to use Swagger UI for API testing. We will start by discussing  what Swagger UI is, and why it’s worth using, and then move on to the tutorial.

What is Swagger?

Swagger (now known as the OpenAPI Initiative, under the structure of the Linux Foundation) is a framework for describing your API by using a common language that is easy read and understand by developers and testers, even they have weak source code knowledge. You can think of it as a blueprint for a house. You can use whatever building materials you like, but you can’t step outside the parameters of the blueprint… 

Read More

Building a REST API with Swagger and Spring Boot

In this post, Nikolaos Georgiou talks about how to use Swagger tools and OAS to build a REST API with Java and Spring Boot. He focuses on using Swagger Codegen to build out his API in Spring. He highlights the need to know information very well and walks through how to generate the code clearly. Check this out if you’re looking for more information on generating code in Spring.


In this post, I’ll be using Swagger to build a REST API with Java and Spring Boot. Swagger is an API framework. It uses a YAML-based language to define an API and it has a code generator that supports multiple languages.

Tooling

Swagger offers an online editor which is useful to start playing with the language and get familiar with the syntax. But in order to generate some code, it’s handy to have the code generator locally.

On the left side of the editor you can see the YAML syntax. On the right side, a preview of the API, which is updated real-time as you modify the YAML definition…

Read More

Schema First API Design

This guide introduces you to the strategy behind schema-first (sometimes called design first) API design and how to use Swagger tools to get started with the OpenAPI specification. Yos Riady does an excellent job of highlighting the benefits of designing with the OpenAPI specification in mind first. It’s very in depth and a valuable resource if you’re weighing the pros and cons of designing with OAS.


You’re building an API.

You develop a backend service with a few endpoints and deploy it to production. You publish several official language-specific API clients as well as an API documentation. The day ends on a happy note.

The following day, a new feature is being added the API. You have to:

  • Update the server implementation to support the new feature.
  • Update all client libraries (one SDK for each supported platform and language.)
  • Update the documentation.
  • All the above must be consistent with each other.
  • Also, the frontend team is blocked until your backend API is complete. 

You let out a heavy sigh. Is there a better way to do this?…

Read More 

 

Share Your Swagger

Do you want to see your work highlighted on the Swagger Blog? Swagger Spotlight is an opportunity for our community of thinkers and creators to share with the rest of the Swagger community. We are always interested in seeing what people are building with Swagger tools and believe in shining a light on the great work this community is doing.

Submit your idea today!