Jeremy BrownJeremy Brown

My feedback

  1. 133 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…)
      14 comments  ·  General  ·  Admin →
      started  ·  ZZ responded

      Updated information.

      You can already describe URI parameters in structured way with the new API Blueprint format. Refer to https://github.com/apiaryio/api-blueprint/blob/master/examples/7.%20Parameters.md for details.

      The new format is now default and URI parameters are properly rendered in the documentation.


      We are still working on description of http message–body properties (parameters). It is planned in the upcoming revision 1B of API Blueprint – as discussed in https://github.com/apiaryio/api-blueprint/issues/25

      Jeremy BrownJeremy Brown shared this idea  · 
    • 1 vote
      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…)
        0 comments  ·  General  ·  Admin →
        under review  ·  Lukas LinhartLukas Linhart responded

        Thanks for your feedback Jeremy. We suggest documenting only main/functional aspects of the API. It is assumed that not-mentioned URLs+verb combinations return some sort of error code. You could specify common behavior of the API (for example error handling for unsupported verbs/URLs) in the header comments of your API.

        Does that make sense? My worry is that featuring all verbs for all URLs will clutter the documentation, too.

        Jeremy BrownJeremy Brown shared this idea  · 

      Feedback and Knowledge Base