Apiary vs Swagger UI: What are the differences?
Apiary and Swagger UI belong to "Documentation as a Service & Tools" category of the tech stack.
"Easy to use" is the primary reason why developers consider Apiary over the competitors, whereas "Open Source" was stated as the key factor in picking Swagger UI.
According to the StackShare community, Swagger UI has a broader approval, being mentioned in 203 company stacks & 101 developers stacks; compared to Apiary, which is listed in 44 company stacks and 18 developer stacks.
What is Apiary?
What is Swagger UI?
Need advice about which tool to choose?Ask the StackShare community!
Sign up to add, upvote and see more prosMake informed product decisions
What are the cons of using Apiary?
What are the cons of using Swagger UI?
Sign up to get full access to all the companiesMake informed product decisions
Sign up to get full access to all the tool integrationsMake informed product decisions
We just launched the Segment Config API (try it out for yourself here) — a set of public REST APIs that enable you to manage your Segment configuration. A public API is only as good as its #documentation. For the API reference doc we are using Postman.
Postman is an “API development environment”. You download the desktop app, and build API requests by URL and payload. Over time you can build up a set of requests and organize them into a “Postman Collection”. You can generalize a collection with “collection variables”. This allows you to parameterize things like
workspace_name so a user can fill their own values in before making an API call. This makes it possible to use Postman for one-off API tasks instead of writing code.
Then you can add Markdown content to the entire collection, a folder of related methods, and/or every API method to explain how the APIs work. You can publish a collection and easily share it with a URL.
This turns Postman from a personal #API utility to full-blown public interactive API documentation. The result is a great looking web page with all the API calls, docs and sample requests and responses in one place. Check out the results here.
Postman’s powers don’t end here. You can automate Postman with “test scripts” and have it periodically run a collection scripts as “monitors”. We now have #QA around all the APIs in public docs to make sure they are always correct
Along the way we tried other techniques for documenting APIs like ReadMe.io or Swagger UI. These required a lot of effort to customize.
Writing and maintaining a Postman collection takes some work, but the resulting documentation site, interactivity and API testing tools are well worth it.
Two weeks ago we released the public API for Checkly. We already had an API that was serving our frontend Vue.js app. We decided to create an new set of API endpoints and not reuse the already existing one. The blog post linked below details what parts we needed to refactor, what parts we added and how we handled generating API documentation. More specifically, the post dives into:
- Refactoring the existing Hapi.js based API
- API key based authentication
- Refactoring models with Objection.js
- Validating plan limits
- Generating Swagger & Slate based documentation
We use Swagger Inspector in conjunction with our universal REST-API "Charon". Swagger Inspector makes testing edge-cases hassle-free and lets testing look easy. Swagger Inspector was also a great help to explore the Mojang-API, that we are dependent on, because it is the central repository for minecraft-account-data.
We previously used Postman but decided to switch over to Swagger Inspector because it also integrated seamlessly into Swagger UI, which we use for displaying our OpenAPI specification of said REST-API.
Apiary é um excelente ferramente para documentação de sua API e guia para desenvolvimento do back-end. Utilizamos ele para garantir a informação correta a cada end-point.