Swagger has come a long way. The project got renamed
("Open API") and it seems to have a vibrant community.
If you are not familiar with it, it's a specification to describe your HTTP
endpoints (spec here) that
has been around since a few years now ~ and it seems to be
getting really mature at this point.
I was surprised to find out how many available tools they are now. The
dedicated page has a serious lists of tools.
There's even a Flask-based framework used by Zalando to build microservices.
Using Swagger makes a lot of sense for improving the discoverability and
documentation of JSON web services. But in my experience, with these kind of
specs it's always the same issue: unless it provides a real advantage
for developers, they are not maintained and eventually removed from projects.
So that's what I am experimenting on right now.
One use case that interests me the most is
to see whether we can automate part of the testing we're doing at Mozilla
on our web services by using Swagger specs.
That's why I've started to introduce Swagger on a handful of
projects, so we can experiment on tools around that spec.
One project I am experimenting on is called Smwogger, a silly
contraction of Swagger and Smoke (I am a specialist of
stupid project names.)
The plan is to see if we can fully automate smoke tests against
our APIs. That is, a very simple test scenario against a deployment,
to make sure everything looks OK.
In order to do this, I have added an extension to the spec, called x-smoke-test,
where developers can describe a simple scenario to test the API
with a couple of assertions. There are a couple of tools like that already,
but I wanted to see whether we could have one that could be 100% based
on the spec file and not require any extra coding.
Since every endpoint has an operation identifier, it's easy enough
to describe it and have a script (==Smwogger) that plays it.
Here's my first shot at it... The project is at https://github.com/tarekziade/smwogger
and below is an extract from its README
Running Smwogger
To add a smoke test for you API, add an x-smoke-test section
in your YAML or JSON file, describing your smoke test scenario.
Then, you can run the test by pointing the Swagger spec URL
(or path to a file):
If you need to get details about the requests and responses sent, you can
use the -v option:
Scenario
A scenario is described by providing a sequence of operations to
perform, given their operationId.
For each operation, you can make some assertions on the
response by providing values for the status code and some
headers.
Example in YAML
If a response does not match, an assertion error will be raised.
Posting data
When you are posting data, you can provide the request body content in the
operation under the request key.
Example in YAML
Replacing Path variables
If some of your paths are using template variables, as defined by the swagger
spec, you can use the path option:
You can also define global path values that will be looked up when formatting
paths. In that case, variables have to be defined in a top-level path
section:
Variables
You can extract values from responses, in order to reuse them in
subsequential operations, wether it's to replace variables in
path templates, or create a body.
For example, if getSomething returns a JSON dict with a "foo" value,
you can extract it by declaring it in a vars section inside the
response key:
Smwogger will use the query value to know where to look in the response
body and extract the value. If the value is not found and default is
provided, the variable will take that value.
Once the variable is set, it will be reused by Smwogger for subsequent
operations, to replace variables in path templates.
The path formatting is done automatically. Smwogger will look first at
variables defined in operations, then at the path sections.
Conclusion
None for now. This is an ongoing experiment. But happy to get your feedback
on github!