Microcks allows us to take a spec file, such as an OpenAPI spec, and create a working server with local endpoints that we can mock, prototype and test against.
A great use case for this is a project I've worked on that has an API hosted in AWS. This could be expensive if we were developing features and writing tests that hit the live endpoint and rack up a huge AWS bill. Instead, we can point our dev and test code at our local instance of Microcks for a virtually identical DevEx
This post is a quick fly-over to getting your spec loaded in Microcks and takes a quick look at what you can expect, and why it could be useful to you on your next project. For a much deeper dive and more information, you should view https://microcks.io/ and their great documentation!
1. Install Microcks with Docker Desktop
Within Docker Desktop, go to the extensions panel and click "Add Extensions" to view the extensions marketplace.
Within the marketplace, search for "microcks" and click install
Then choose the Microcks plugin from the Extensions listing and click "Launch Microcks"
If successful, you'll see the state change from "stopped" to "running" and you can then click the given URL to view the Microcks UI in your web browser (usually http://localhost:8080, but you can specify a different port if you require)
2. Import a spec.yml
For our example, let's grab an example spec such as this one from @lornajane which contains a demo with planets and webhooks: https://github.com/lornajane/flask-planets-and-webhooks/blob/master/openapi.yaml
Once you've saved your example, navigate to the Importers tab and click the "Upload" button
and click "Choose file" to upload our spec, followed by "Upload" to upload it
If successful, we should now see our API listed in the "APIs | Services" tab
3. Explore your API
In the "APIs | Services" tab, click the blue text belonging to your API. Doing so will take us to the overview page for your API
If we click on "View documentation" you'll be taken to a page that lists all of your API endpoints. Clicking on any of your endpoints will expand the view with relevant content. In the screenshots below, you can see that we get a human-readable and parse-able interpretation of the spec we added.
We can see key information such as the path parameters that the endpoint is expecting.
We can also see the response scheme that helps us understand and plan for the many types of responses we can trigger. For example, we can see here that a 200 response will return different data from the 400 response
We also can see in the above screenshot that we're given an example endpoint structure, including any URL params, and will give us some example responses based on the data in the spec.