Demonstrate Microcks Mocking

[philsturgeon]

This branch aims to get the Train Travel API working with Microcks as smoothly as possible, with good dynamic responses and minimal errors showing up in the Spectral ruleset.

[github-actions]

🤖 API structural change detected:

Modified (1)

• GET /stations
  • Response modified: 200
    • Content type modified: application/json
      • Property added: links

Preview documentation

Powered by Bump.sh

[philsturgeon]

@paulRbr @scharrier I have updated the microcks pull request as it had a few unrelated changes, so you can clearly see what needs to be done in order for a OpenAPI to work with both Bump.sh and Microcks.

Microcks currently requires a) named examples, and b) variables in the response examples in order to reuse request parameters.

The names examples show up the same as usual, but they do make the OpenAPI a little more clunky.

The variables in the response show up literally in Bump.sh and this of course makes no sense to the user.

So, questions:

1. Are we ok with the Train Travel API using this slightly more clunky OpenAPI for named examples? If not... I had mentioned to Microcks about supporting single example instead of only working with named pairs, but named pairs can be very powerful if used correctly. If we need Microcks to roll out a new feature before pushing collaboration this could be a blocker.

2. Are we ok with the Train Travel API demo showing these variables in there, or should we try and avoid that somehow.

• A. Bump.sh Docs adds functionality to reuse values from the request to populate those variables and make for a heck of a powerful feature nobody else currently has.
• B. We use overlays to add these examples and have a second Microcks-enabled OpenAPI document that is hosted elsewhere, which we then make available for the microcks team to pull in.

Probably B, I thought of that mid writing this all out. 😆

Still, thoughts on this would be welcome when you have a moment.

[philsturgeon]

If we manage to get a hosted microcks instance up and running I'd like to update this to point there. @lbroudoux

[lbroudoux]

We now have a ready to use / managed instance for hosting the Train Travel API => https://try.microcks.io using guest/guest. I don't have communicate on this yet but can already have a look (even if the API is not yet loaded in)

[philsturgeon]

I've had a look and its really cool. When we get the TT API into it I will update this.

[lbroudoux]

Are we ok with the Train Travel API using this slightly more clunky OpenAPI for named examples? If not... I had mentioned to Microcks about supporting single example instead of only working with named pairs, but named pairs can be very powerful if used correctly. If we need Microcks to roll out a new feature before pushing collaboration this could be a blocker.

I tried this after our conversation but relying on single default example raise a lot of other question in the case of multiple response codes, response formats and so on. It works with very basic API (1 input/1 output) but doesn't work with realistic ones.

B. We use overlays to add these examples and have a second Microcks-enabled OpenAPI document that is hosted elsewhere, which we then make available for the microcks team to pull in.

This is definitely possible to move those "advanced" examples using expressions into another OpenAPI file. APIVersion your declare on the Microcks Hub can reference many artifacts and these ones will be merged during the import. So expressions won't "pollute" the OpenAPI spec.