api-blueprint Support for comments

From what I saw on apiary.io I can't comment out blocks of the documentation which is very important for me. Even putting HTML style  comments doesn't work.

Dec 04 '14 08:12 AlexGrafe

Hey @xanderiel I am trying to avoid introducing comments to the API Blueprint – as I believe that could lead to blueprints fragmentation. However I would like to know about your use case for them – perhaps we will be able to address it in a different way ?

Dec 09 '14 15:12 zdne

Please reopen with some additional input if needed.

Apr 27 '15 18:04 zdne

:+1: We'd like to use comments to save work-in-progress. Since it is a single file documentation style, I think some kind of WIP format would be helpful.

Dec 22 '15 02:12 toobulkeh

@toobulkeh Is your WIP about the description or the layout of APIs ? Could there be another way to satisfy it?

Dec 22 '15 16:12 zdne

Hi there,

I think the possibility to create comments is really important. Below 2 use case:

junior readers Some of the people who are going to use the api may need some extra info, which is not to be displayed but that would help to write documentation consistently.
private sections In my case, it is very important to be able to create private sections. That is, parts of the documentation that are not to be published to the open world. It may be an unstable endpoint, which exists but only for a brief period of time.

I refuse to create 2 separate documentations, as it is the best way to async docs. Instead, I am using comments to indicate parts that are to be preprocessed before sent to apiary. example:

<!-- <dev> -->

### Create Foo [POST]

Create a foo.  This is not yet disclosed.

+ Parameters
    + account_id (number) - Id of the account

+ Request

    + Headers

            Authorization: Bearer YOUR_ACCESS_TOKEN_HERE

    + Body

            {
                "label": "foo fighter"
            }

+ Response 200 (application/json)

        {
            "success": true
        }
<!-- </dev> -->

A script preprocesses the input.apib file and removes the parts for the public. However, we are able to have an internal doc that documents this endpoint.

On my side, the works both on apiary and local, and it is a blessing ;). However, I just wish that in code parts, it was not considered as a syntax error but as an intended design.

Jan 12 '16 16:01 mx-c

We are working on a larger api spec and use gulp inclusion, templates, hercule etc. Comments would help explain what's happening, why and how.

Jul 12 '16 13:07 weaselmetal

@weaselmetal that makes sense

Jul 14 '16 11:07 zdne

+1

Jul 18 '16 02:07 nayanbhana

+1

Aug 03 '16 13:08 chano

+1

Sep 06 '16 14:09 dcaron

+1

Oct 05 '16 15:10 jasonwatt

+1

Nov 01 '16 21:11 dougchase

+1

FYI, we'd like to put a reference to the constants from our codebase to the API blueprint, so that when we change the constant, we can track its presence in the API blueprint. For example:

Note that the maximum length of the tag string is
64 characters <!-- =EXECUTION_TAG_MAX_LENGTH -->.
You will receive an error if you try to use a longer string.

Dec 05 '16 15:12 jancurn

+1

Dec 08 '16 11:12 bovin-a

+1

Dec 17 '16 00:12 mitchellporter

+1

Feb 01 '17 18:02 xrochoa

+1

Mar 07 '17 19:03 BrunoQuaresma

+1

Mar 09 '17 16:03 Vratislav

+1

Mar 19 '17 23:03 grellyd

+1

Mar 23 '17 16:03 DavidBM

+1

Apr 13 '17 13:04 vioan

👍

This is really useful while writing documentation from scratch. As far as i'm aware there's still no way of making comments for myself to remind me what resources are in each route, so that I know what I need to include when getting around to writing docs for them & don't miss anything. E.g:

jsonapi_resources :groups
jsonapi_resources :group_members
post '/group-invites/:id/_decline', to: 'group_invites#decline'
get '/groups/:id/_stats', to: 'groups#stats'

Only way to do it right now is to fill the documentation with useless information for developers...or just not do it and hope for the best 😅

May 26 '17 08:05 wopian

For the WIP, the comment section will be very useful.

Jun 07 '17 17:06 sureshkamidi

➕ 1️⃣

I'd like to be able to leave comments because I want my teammates and future maintainers of the documentation to know what code the docs are based on, for example:  would save them time from searching the codebase if for any reason the docs and the code get out of sync.

Jul 25 '17 23:07 johana-star

I am using apiary for both internal specification for our devs building the api and for providing documentation to devs at other companies consuming our api. Comments would be useful to me so that I can leave more detailed instructions than just a data structure. I would also like to be able annotate responses and provide a list of possible responses for a single error code so that I can document causes for different error codes and the expected behaviour for handling them. Inline comments in data structures would also be good for describing the function that different options perform. eg: We do video streaming services, and we have a field in some structures that can take the values "push" and "pull" to describe how the media is intended to leave our servers. Currently this requires separate documentation