Having online documentation is great for developers to work with each other but it would also be good to be able to export the document to include in other system documentation or to be able to email it to 3rd parties.504 votes
Apiary now has a print stylesheet for the generated Docs.
It uses numbering + table of contents and displays the examples with language you have selected in the language-dropdown.
The preferred way of sharing the documentation with 3rd-parties is through People settings (add viewers). However printing now looks great.
Feel free to comment.
Provide some way to indicate the required authentication (if any) for any given call. We use a combination of user credentials and api keys for our http basic auth, and would really like to see some way to support http authentication as part of the documentation and mockups. Also for Oauth scenarios perhaps?248 votes
We are working on http auth support as part of our blueprint overhaul.
The current system lets you simulate an API call, but sometimes a mock call won't explain everything. Some parameters in the call might be required while other things aren't; others might only be required when a different parameter is included; there could be an option with five different choices and another with a boolean and you could want to explain what all the options do.
Thus I think there should be a place to describe the possible parameters and their options in the request and response, something like http://developers.dwolla.com/dev/docs/transactions/send133 votes
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
For example http://api.mydomain.com/docs133 votes
We are offering embedding as part of our Apiary for Companies plan. Please contact email@example.com if you want to try it out.
That said, we are going to offer simpler & cheaper possibility by using CNAME. This is planned to be available this year.
The platform is missing change history and an ability to save draft versions.
What happens if someone deletes everything by accident?114 votes
We do track revisions internally, but we are yet to release proper API and UI for that. It is fairly high on our list, though.
It would be great to have multiple API files stored in 1 Github Repository. We have internal APIs that are documented separately, however we don't wanna have a separate repository in Github for each API.113 votes
We are working on this one. Stay tuned, and let us know here if you’d be willing to betatest.
Developers who use a branching/tagging conventions in git (such as GitFlow: http://nvie.com/posts/a-successful-git-branching-model ) would appreciate this being reflected in apiary.
In this way the documentation for the current stable release of an api might be drawn from the repository's master branch, while previous versions would be available at tags, and ongoing work towards the next release could be viewed and discussed at a develop branch.
If the mock api were similarly configurable it'd be extra brilliant.110 votes
We are working on the initial workflow support using git branches.
Currently one can define a single HOST endpoint that will be displayed in the right-hand column when viewing an API. It would be great if we could create multiple HOST definitions for different environments and name them descriptively.96 votes
We are not sure if multiple HOST headers are the right solution, but we definitely want to provide a way to use Apiary against staging environments.
With just 4 api calls the file is already getting pretty big, I would welcome being able to organize the API blueprints into subdirectories somehow.
Also being able to identify an API call and link to it both from outside (as in: use THIS api call to do what ou wish) and inside (this api call is the same as THIS except for ...)86 votes
Undocumented pre-alpha is live, but not all in-product edges are fine-tuned properly.
Please let us know (e-mail to firstname.lastname@example.org) if you want to use this feature, we will give you a howto.
We have started to work on some OAuth2 support and testing it with some customers.
Current status is “very alpha”; you can only mark the whole API as being authenticated and we do not provide any support for mock server yet.
An activity feed (like Trello for example) of all the actions that have taken place on the API (edits, deletions, comments etc). This would add a massive amount of value around the collaboration on a Blueprint.73 votes
We are planning to look into it soon.
Provide a way to populate some parts of response with "variables".
* Provide "api base" that is corresponds to generated mock server URI
* Provide same variables that are specified in templated URI62 votes
Comments are currently quite well hidden. You have to expand the endpoint, and then click the Comments tab to see them at all.
More: there's currently no email notification of new comments, even if they're replies to something I posted myself. This makes it awkward to iterate with clients on an API design; you have to send them "I've replied to your questions" emails all the time.44 votes
Agreed, working on it. Comments are much more visible in the next iteration of our documentation visual.
(Not only) notifications are planned after that, disguised as activity feed: http://support.apiary.io/forums/120125-general/suggestions/3872771-add-an-activity-feed-for-blueprints-so-you-can-tra
When JSON schema is provided, inject documentation (in form of table?) into related resource.41 votes
When entering JSON format data I take the junk spit out of my actual API implementation and enter in the blueprint. It's not normally pretty printed. You could use JSON Lint.40 votes
The way in which the APIs are organized should allow from groups of APIs to be set. If you have dozens or hundreds of APIs you want to be able to group them in functional clusters. As it is today, they are all below a common root node, making them hard to manage if you have too many.
The current way to list your APIs in the top dropdown menu is easy enough if you have a couple of APIs, but cumbersome if you have dozens of APIs.
This is critical for the insertion of big sets of APIs.38 votes
Agreed. As we are starting to have heavy users, we’ll have to provide such functionality.
I want to be able to describe my data model and then tell my various routes that they either expect that model passed in and/or promise to return that model. That way I don't have to describe my model once for POST and again for GET and again for PUT etc...36 votes
Dear Christopher, this is definitely planned for an upcoming revision of New API Blueprint Format (most likely 1B).
I plan to introduce “data dictionary” and payload / asset referencing that should address these needs.
Than you for your input, much appreciated!
GitLab ist a cloud- or self-hosted code colaboration platform.35 votes
As gitlab recently added usable API for handling since, we are considering this.
We'd like to store the blueprint in bitbucket, it would be nice if there was support for generic git repositories for that reason.
We definitely plan to provide update API with example hooks.
Display warning if example JSON in request/response is not well-formed.32 votes
- Don't see your idea?