Slightly off-topic:
Are there any tools which can validate an OpenAPI Specification against a running instance of the API it describes?
I've played around with apiaryio/dredd, but was hoping to find something more targeted towards OpenAPI/Swagger.
Are there any tools which can validate an OpenAPI Specification against a running instance of the API it describes?
I've played around with apiaryio/dredd, but was hoping to find something more targeted towards OpenAPI/Swagger.
I have own experience only with "server-side" of Swagger validation. Some time ago, I had to build a simple stateless "gateway" style Node.js backend for a customer webapp. It took API requests, checked authorization and then fetched data from a couple of non-public services, and combined them to a reply JSON for consumption by the frontend webapp.
I wanted to keep the backend really simple and have guarantees it was always returning good data, so I could focus on the more complex frontend code. I thought a "specification-driven" approach would be suitable, where I first described my intended backend REST API with Swagger, and then wrote the Node.js code that implemented that REST API specification. Usually, things are done exactly vice-versa: you write the backend code, and then generate the spec that describes your implementation.
I think I ended up using the swagger-express-validator library to a) validate incoming JSON/form POST requests, b) automatically select the correct Node.js controller that should serve the request, and c) validate that the HTTP/JSON replies the controller eventually returned were correct (per the Swagger spec).
https://github.com/gargol/swagger-express-validator
It worked quite well. The Swagger served as kind of a "index" of the backend, similar to a C header file, and if you did an "oops" and returned bad data you would immediately get a fatal error during development. I caught multiple corner cases where the upstream APIs were returning unexpected data that would have normally been only discovered by monkey testing the UI.
This library allows choosing the NodeJS/Express controller by a Swagger spec, but I think I ended-up rolling my own:
Basically, you setup test cases for your API(s), and we automatically contract test the inputs/outputs of the requests against your OAS specification where possible. If anything does not validate against the schemas defined in your OAS specification, the test will fail with descriptive errors. If your OAS is ever updated, those changes will automatically work in the tests, since the tests are just referencing the OAS spec (not duplicating data from it).
A couple more things:
- You can create these tests with our visual UI, or write the underlying JSON that describes the tests by hand.
- You can run the tests inside of our UI, or install Prism (our command line runner) to run them completely outside of Stoplight (CI, terminal, etc).
- We plan to support OAS3 later in Q4 of this year.
We live and breathe API tooling and specifications. If you have any questions about process, our product, API strategy, etc, happy to chat - just shoot me an email at marc [at] stoplight.io!
Fwiw, an interesting inverse approach is to define routes/apis/validation directly with swagger specs, which there are a few libraries in various languages for.