Render API Blueprint as Markdown

[zdne]

API Blueprint is a Markdown based description language for Web APIs.

Ideally an API description – an API blueprint – lives in the repository with the API implementation, readable by API users and integrated with a CI which tests any changes to API implementation or the blueprint itself.

An example of an API Blueprint can be found here. Some real-world examples are here (Tesla Model S API) or here (PODServe API).

Not sure whether this PR should be to master or release-1.0.1. Let me know, should something need to be changed.

[honzajavorek]

👍

[bkeepers]

@github/api have you guys ever used this? What are your thoughts?

[pengwynn]

/cc @gjtorikian

[bkeepers]

Here's what it looks like with our current styles. https://github.com/apiaryio/api-blueprint/blob/master/examples/Gist%20Fox%20API.md

It's not great. If we were to adopt this, we'd probably want to use a real parser for it and make sure the styles look good. I think I'm 👎 until it becomes more widely adopted.

[opichals]

👍

This could help github lead developers in the right direction in the API documentation space which alone deserves a great deal of attention with the cloud trend we are all into.

As @apiaryio is becoming one of the very few publicly acknowledged and practically used REST API description languages I would vote to add support to github as soon as practically possible.

[andreineculau]

I've been an advocate of @apiaryio for a while now, but despite all the good words that one can say about them and their work, this PR is first and foremost about adding knowledge to github's "renderer" about an alternative Markdown file extension, and not about how github could pitch in the API community.

With that said, if I step into github's shoes, I'd ask myself 2 pragmatic questions:

• Is there a precedent?

  There is, for .litcoffee. I don't know the history and git blame was of no help, but there is at least this one extension for a file format based on markdown (it is not 100% markdown, because any indented blocks should be treated as coffeescript).

• How well-known is this file extension?

  Numbers, please :) I can only speak subjectively: if I'm with one leg into APIs, and the other into CoffeeScript, .apib comes up more often than .litcoffee. After the day when Literate CoffeeScript was born, I didn't see it once actually (and based on the report card, I should have).

It's for these reasons that I 👍 this PR, despite my bias.

@bkeepers is surely right that the rendered content is not "great" (far from this or that) , but that is an optimization on a different scale than this PR's optimization.

[jana4u]

👍

[bkeepers]

I think we're going to hold off on this for now. Let's revisit it in a few months and see what adoption looks like and if anyone is interested in implementing some really great styles for it.

[zdne]

@bkeepers

Thanks for your consideration.

Can you provide any additional guidance and/or criteria on this? Is there any quota that should be met? API design is an emerging niche discipline and as such API Blueprint will never be as widely adapted as a general-purpose programming language.

As for the styles – do you mean the styles embedded in the rendered HTML for a better aesthetics than the default GFM look?

[kuba-kubula]

👍 because it is markdown, after all

[bkeepers]

Sorry, I don't have any specific guidelines to offer. Right now we're focusing really hard on improving the quaility of our existing features. We already have a bunch of markup formats that we want to do a better job of supporting, and adding another one right now won't make that easier.

As for the styles – do you mean the styles embedded in the rendered HTML for a better aesthetics than the default GFM look?

Not embedded styles, but styles that we could add to GitHub to make the rendered output look better. One way to help better present the argument for including this would be to show what it could look like. So you could:

1. Create a static HTML page that has the rendered API blueprint markup
2. Hotlink to GitHub's CSS: <link href="https://github.com/assets/github.css" rel="stylesheet" type="text/css">
3. Add additional styles that make it look really great

[zdne]

@bkeepers

Understood. You are trying to keep up the quality & integrity. Same as I do with API Blueprint. Will try it later when it gains a bigger momentum.

Just for the record here are some rendered static sites:

• one
• two
• three

As generated by https://github.com/danielgtaylor/aglio and https://github.com/subosito/iglo. I would love to get there eventually with API Blueprint integration on GitHub. This PR could help in finding out whether API Blueprint can become a "first class citizen" on GitHub.

[dallasgutauckis]

👍 for having this available.

Although having a beautiful, pragmatic rendering of API blueprint files would be awesome, I think a reasonable first step is at least distinguishing them from current formats (markdown) by filename (.apib). Allowing .apib to render as Markdown (APIB's super syntax) means developers won't have to use .md extensions, which allows GitHub/contributors to provide enhanced syntax support incrementally without having to notify users to consider renaming their files ;-)

As for the 'critical mass' question, my general opinion is that concise, well-structured, even testable API documenting is probably not the most common thing to do and therefore is likely to have a lower density altogether. That being said, I think providing support for formats for doing so on GitHub is somewhat critical for greater adoption as GitHub tends to be somewhat of a trendsetter. Whether API Blueprint is the 'right' way for documenting APIs is somewhat irrelevant — as we know, GitHub supports a myriad of languages and markup formats, so deciding on one isn't important. I think if someone (even an outside contributor) is at least willing to provide basic support, GitHub should permit them to do so in order to provide something to those who wish to use it.

[josegonzalez]

👍

I think that API Blueprint is starting to achieve some level of notoriety amongst people concerned with building great, well-documented APIs. For instance, one of the top books on leanpub makes reference to API Blueprint, and the author is quite active in suggesting that others use API Blueprint (or some similar system).

While having rich integration between github and apib would be 💰, it appears to me that at least giving some acknowledgement to this sort of format is good for the documentation community in general.

[nodesocket]

As a hack, what we did is symbolic link .apib to README.md, works quite well. See https://github.com/commando/API

[josegonzalez]

@bkeepers Any chance this can be looked at again?

[bkeepers]

We recently started rendering .Rmd as just plain markdown. We could probably do the same with API blueprint. We just don't want to maintain another parser right now.

If someone wants to submit a PR to do that, I'll pull some other GitHubbers in to see what they think.

[josegonzalez]

All this PR did was add .apib as a valid markdown extension. Can this PR be merged?

[bkeepers]

Sorry, I didn't re-read the beginning of this conversation and was remembering it wrong (Seriously, how was February so long ago?).

I'm still not crazy about the look of the doc linked above, but https://github.com/commando/API looks great. I have a feeling we'll be getting bug reports in a few months that our formatting on some documents is bad.

/cc @jasonlong @mdo @ymendel do you have any thoughts on this?

[jasonlong]

Adding .apib as an extension that will render as Markdown seems ok, but I'd defer to @bkeepers on the technical ramifications of doing so.

As far as styling goes, the commando example looks pretty good to me. It would be nice to have specific styling for sections like the response / payload blocks (using the + character), but I don't think that would be possible without a new parser (e.g. those response blocks currently render as lists with a .task-list class).

[ymendel]

I think it's easy to add this extension as something to be parsed as Markdown, but that it's a little off. This is probably because API Blueprint has more differences from Markdown than R Markdown has. That is, API Blueprint is based on Markdown, with some extra structure and expectations. R Markdown is just Markdown with R code in it.

(This is a simplification, I know.)

That said, maybe this is good enough. Will the API-Blueprint–using community understand the limitations and know that they're not getting the full thing (right now)? Can we make some small tweaks later to improve this?

Also, maybe @mtodd has a bit of time to take a look at the task-list stuff. That seems odd that we'd do anything task-list-y there without the [ ].

[dallasgutauckis]

The more I think about this, the more I'm not sure which approach is better.

Sides:

Format .apib as Markdown

• Get the benefit of more beautifully-rendered text
• Rendered mostly as API blueprint is intended to be rendered

Don't format .apib as Markdown

• Get the benefit of concise structured formatting that is more parseable when reading for the intents of API-blueprint format.

Those things being said, @zdne is the primary contributor to API blueprint and I think we should probably just default to which one he would prefer.