More than 1 example per method/content type?


#1

Hi all,

I was wondering if it is possible to specify more than one example for the same content type in a service. For example a GET method with application/json, can we specify more than 1 example?

Kind regards,

Alex


#2

Hi @agines,

unfortunately that is not possible yet. Is it something you need for your use case and if so can you elaborate more on that?!

Cheers,
Christian


#3

I actually thing this is a definite need for many APIs. There are query parameters which can result in subsets of a resource, showing examples of each query parameter and what it returns would be very useful to give a developer reading the doc a much better idea of what to expect with the options available.

I thought the 1.0 spec was adding this ability?


#4

Thanks for the replies guys.

It’s not something that we need at the moment, but maybe in the future so that’s why I was asking. Maybe a good workaround is to put several examples inside a unique example section of a method?

Kind regards,

Alex


#5

That’s a valid point @agines. @christian_vogel would it make sense to have the documentation of examples in Markdown format span one example… that is to say, just use good Markdown format to list several examples and then maybe put that in a file and !include it in the example section? Perhaps that is the right way to do it?


#6

Hi @justjacksonn - the problem on this approach is that the Mocking service is using the current format and would have problems with a markdown language. That count in all mocking service, not only the one inside the API Designer. So I would try not to do it like that. It’s difficult to say how something like that can be achieved without influencing the current toolset around those examples definitions.

I think you can solve this with some of the language styles in RAML 1.0 already.


#7

Multiple examples would be welcome.

My expectation would be:

  • keep each example file as really single file (do not embed it into markdown)
  • plan for a tool, which would take all presented samples and validate them against provided schemas (which can already be part of the documentation). This would allow for quick API spec check, detecting forgotten outdated examples.

In past I had simila framework (called DirYaml), where we had also a place for mapping request to response samples and even providing examples of broken files (denoting it by an extentsion). I would say, broken examples are not really needed.