Microcks for dummies

Supervinh — Thu, 09 Jan 2025 00:19:39 +0000

🤔 Microcks: For Whom and For What?

How can you tell if API documentation:

Is properly documented ?
Is sufficient for effective usage ?
Allows partners/clients to efficiently test ?

This is exactly what Microcks, an open-source tool, promises to deliver. Its benefits have already been explored in one of OPT-NC’s public APIs for agency waiting times.

// Detect dark theme var iframe = document.getElementById('tweet-1862247586411028971-410'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1862247586411028971&theme=dark" }

🤓 Spoilers

📜 Annotations and REST API Documentation Quality

Why document a REST API using annotations directly in the source code?

💡 Clarity for developers: Annotations precisely describe endpoints, parameters, and responses, making the API easier to understand.
🔄 Automatic updates: Generating OpenAPI documentation from annotations ensures that it stays aligned with the source code in a simple and efficient way.
📚 Concrete examples: Annotations also allow adding example calls, helping developers understand practical use cases.

Here’s an example of annotations:

@GET
@Path("/endpoint")
@Operation(
        summary = "Operation summary",
        description = "Detailed description"
)
@APIResponses(
        value = {
                @APIResponse(
                        responseCode = "200",
                        description = "OK response",
                        content = @Content(
                                mediaType = "application/json",
                                schema = @Schema(implementation = MyClass.class),
                                examples = {
                                        @ExampleObject(
                                                name = "Example 1",
                                                value = "{'key':'value'}"
                                        )
                                }
                        )
                )
        }
)
public ReturnValue myFunction() {}

And to describe request parameters:

@GET
@Path("/endpoint/{id}")
public ReturnValue myFunction(
        @Parameter(
                description = "Expected ID",
                schema = @Schema(type = "integer"),
                examples = {
                        @ExampleObject(name = "Example ID", value = "123")
                })
        @PathParam("id") int id
) {}

Validation and Security with Swagger:

✅ Validation of parameters and responses.
🔒 Endpoint security to prevent injection attacks.
🚫 Rejection of invalid values (e.g., negative numbers for non-allowed parameters).

But documentation - and hence its quality - must also be tested!

💼 Enter Microcks: This open-source tool generates mocks from OpenAPI annotations, enabling:

🌐 API testing without actual deployment.
🧪 Evaluation of documentation quality and completeness.
📊 Scoring for OpenAPI compliance to ensure high standards.

With Microcks, documenting is not just writing, it ensures everything works as expected, leading to robust, well-documented APIs. -> ...that can be embedded as part of a CI

🚀 Microcks: Boosting Developer Experience

Thanks to annotations and the mocks generated by Microcks:

📝 Clarity even before development: API functionalities are defined upfront, making communication between developers, test managers, project managers and future users easier.
⏱️ Time-saving: Development and documentation can progress in parallel, optimizing project resources, allowing those depending on the API to start development even before the API itself is implemented.

Microcks transforms how APIs are designed, tested, and shared, creating a seamless and efficient DEVEX (developer experience).

🔍 Microcks and the Testing Pyramid

Among the various representations of testing strategies, Watirmelon’s model stands out as particularly insightful.

🧩 Microcks fits into the Automated API Tests layer, with a particular focus on Contract Testing, ensuring that APIs adhere to their specifications.

🎯 Personal and team benefits

✅ Documentation quality: I was pleasantly surprised by the clarity and precision of the documentation provided by Microcks.
🎨 Intuitive user interface: The UI is simple, intuitive, and very enjoyable to use, making the tool accessible right from the start.
⚡ Developer responsiveness: The contributors of Microcks are highly active on GitHub and respond quickly to issues, which is reassuring when resolving potential roadblocks.
🚀 Unblocking my tests: In my last project, I struggled to mock calls to OpenSearch. With Microcks, I no longer need to mock the calls. I can simply simulate the database to contact, which saves time and greatly simplifies testing.
🔮 Usefulness for future projects: Microcks will be invaluable for my future projects, especially during the development phases. Instead of relying on paid APIs, I can simply use my Microcks mock, which is both more economical and practical.

Microcks has proven to be a powerful ally, not only for this project but also for those to come.