I suggest you ...

Allow to describe a response in plain Markdown

I'm using the new *X-1A* syntax which supports multiple responses, though only when the response code is different (could not manage to have responses with the same response code; please let me know how to accomplish this).

Since there are multiple response going one after another, in the rendered examples view it is difficult for an API user (not API developer) to quickly understand the difference between each responses since they all refer to the same request resource. It would be nice to optionally allow to describe each response in plain Markdown syntax.

10 votes
Vote
Sign in
Check!
(thinking…)
Reset
or sign in with
  • facebook
  • google
    Password icon
    I agree to the terms of service
    Signed in as (Sign out)
    You have left! (?) (thinking…)
    Esen SagynovEsen Sagynov shared this idea  ·   ·  Admin →
    started  ·  Lukas LinhartLukas Linhart responded  · 

    This is possible to do in the new format, but we are not displaying this properly in the old documentation.

    We certainly plan to fix this and I’ll keep you posted once it’s live.

    2 comments

    Sign in
    Check!
    (thinking…)
    Reset
    or sign in with
    • facebook
    • google
      Password icon
      I agree to the terms of service
      Signed in as (Sign out)
      Submitting...
      • ZAdminZ (Admin, apiary.io) commented  · 

        Absolutely. You can already discuss respective payload (requests, responses and models) in API Blueprint as specified here: https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#Payload – see "Example (request payload section)"

        However as Lukas mentions, it is displayed in the current Apiary rendered documentation.

        We are working around the clock to bring you the new, completely redesigned, documentation that will fully capture every aspect of the new format.

      • Esen SagynovEsen Sagynov commented  · 

        I would be happy if you let me know how to do this in the new format. Even though you don't want to open this publicly yet, if it is possible to use it, please let me know.

      Feedback and Knowledge Base