This is the first edition of Swagger Spotlight – a blog series that focuses on the great work Swagger users are doing around the world. If you are building a project with Swagger tools, you have a helpful tutorial, or just have something to say about Swagger and the API industry, we want to hear from you. Submissions are OPEN!
Thomas Pollet is a Freelance IT Consultant out of Belgium
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.
This was a python project using the flask-restful REST implementation with the SQLAlchemy ORM, so the idea was to extract database object schemas from the SQLAlchemy class declarations and the flask-restful endpoint definitions to generate the OpenAPI specification. This worked out very well and I’ve since improved the implementation and functionality and made the project available as an open source python-pip package: safrs.
safrs is an acronym for the main technologies used: SqlAlchemy, Flask-Restful & Swagger. The purpose of this framework is to help python developers create a self-documenting JSON API for sqlalchemy database objects and relationships. These objects can be serialized to JSON and can be created, retrieved, updated and deleted through the JSON API. Optionally, custom resource object methods can be exposed and invoked using JSON. Class and method descriptions and examples can be provided in yaml syntax in the code comments. The description is parsed and shown with SwaggerUI. This package only has support for v 1.0 and v 2.0 currently.
Example Script
I have created a small example script to demonstrate the package's functionality (a running version of the example can be found here). Running this script will expose two classes (Users and Books) as REST endpoints. The User class definition looks like this:
class User(SAFRSBase, db.Model):
'''
description: User description
'''
__tablename__ = 'Users'
id = Column(String, primary_key=True)
name = Column(String, default='')
email = Column(String, default='')
books = db.relationship('Book', back_populates="user", lazy='dynamic')
This class will automatically produce a OpenAPI specification and jsonapi-compliant endpoints:
The software can also detect and expose database relationships, the “books” relationship defined in the User class from the example creates following endpoints:
The JSON data expected by the API will also be automatically generated by using a sample object instance:
It's also possible for developers to describe additional OpenAPI specification details as yaml-encoded comments (eg. the "description" key in the User class will be parsed and used as the description in the UI).
Besides the benefits of using the OpenAPI specification for your project, using the safrs approach has a number of additional advantages:
- The OpenAPI specification is always consistent with the implementation.
- There's less manual work involved in creating and maintaining the specification.
- The API is compliant with the jsonapi
Since the number of JSON webservices will continue to grow, I believe standardization, visibility, compartmentalization and automation is increasingly important in managing the complexity of modern software microservice architectures and that's why technologies like Swagger and safrs may bring a lot value.
If you're interested in trying this out for yourself, or learning about more features and examples, head over to the project's github page.
If you'd like to be featured on our Swagger Spotlight series, click here to submit a topic!
Learn more:
Thanks for reading! Looking for more API resources? Subscribe to the Swagger newsletter. Receive a monthly email with our best API articles, trainings, tutorials, and more. Subscribe