Requesting guidance to contribute "Setting custom dispatcher" documentation page

[killerjoker73]

Describe the bug

Hi Microcks Team 👋,

I would love to contribute to your documentation as part of the ongoing refactoring effort. I noticed that the page titled Setting custom dispatcher is currently marked “To Be Created”, and I would like to contribute by writing it. I would like to write the full blog/documentation. But, As mentioned in the goals on the blog’s webpage, I would like to proceed with the first goal, which is:

• 'Load a sample API and explain how to proceed via the UI.'

Since I’m new to Microcks and still learning the internals of dispatchers, I’d appreciate a bit of guidance before I start writing the draft.

Could you please help me with the following:

1. Should the guide begin with an overview of what custom dispatchers are and when they're used, or is there another concept you’d prefer I explain first before jumping into step-by-step instructions?

2. Is there a specific sample API or example you'd recommend I use for demonstration?

3. If there is anything else that I need to keep in mind for achieving our first goal i.e. - 'Load a sample API and explain how to proceed via the UI.'

Thank you
Best Regards

Attach any resources that can help us understand the issue.

[github-actions]

👋 @killerjoker73

Welcome to the Microcks community! 💖

Thanks and congrats 🎉 for opening your first issue here! Be sure to follow the issue template or please update it accordingly.

📢 If you're using Microcks in your organization, please add your company name to this list. 🙏 It really helps the project to gain momentum and credibility. It's a small contribution back to the project with a big impact.

If you need to know why and how to add yourself to the list, please read the blog post "Join the Microcks Adopters list and Empower the vibrant open source Community 🙌"

Hope you have a great time there!

🌟 ~~~~~~~~~ 🌟

📢 If you like Microcks, please ⭐ star ⭐ our repo to support it!

🙏 It really helps the project to gain momentum and credibility. It's a small contribution back to the project with a big impact.

[killerjoker73]

Hello @yada @lbroudoux
I would like to work upon this issue.
So, can you please help me with the structure or flow of the documentation ?

[yada]

Hi @killerjoker73,

Sorry for the delayed response, and thank you again for your proposal to contribute to the Microcks documentation. We're really happy to welcome new contributors, especially on such an important topic!

Regarding the guide you're planning to work on, here’s some guidance to help you align with our existing documentation structure.

The goal of the page is to cover:

• How to load a sample API and work with it via the UI
• How to add x-microcks-operation attributes and observe the effects after reloading the API
• A discussion on using API Metadata or API calls to achieve similar results

Please take a look at similar guides for reference and aim to follow the same structure. For example:

1. Importing Content
2. Managing Delays

You may also find inspiration in Laurent’s blog post, Advanced Dispatching and Constraints for Mocks, though keep in mind that your guide should remain more accessible and less advanced.

For consistency, we recommend continuing to use the Pastries API from our sample collection, which is used throughout the documentation 👉 Pastries API Sample

✍️ Recommended structure for a Microcks How-To Guide could be:

Overview

• What the guide covers and why it’s useful
• When a user might need this guide

Concepts

• Definitions of key terms
• Scope of application (e.g., operation vs endpoint level)

Practice

• Step-by-step instructions
• Examples using the Pastries API
• Command-line examples (e.g., curl)

Advanced Usage or Alternatives

• Other methods (OpenAPI extensions, API Metadata, Microcks API)
• Best practices

Wrap-up

• Summary of what was covered
• Links to related guides or topics for deeper learning
• Let me know if you have any questions or want feedback as you go — and thanks again for contributing!

Best regards,
Yacine