api-documentation-tool-research.md

API Tools Recommendation

Swaggerhub

Our recommendation is to use SwaggerHub for building out our documentation and building out some mocked endpoints for partners to see. SwaggerHub is a web app that pulls together a suite of Swagger products. Among to pros listed below, Swagger is also a common documentation tool and we know some partners will be familiar with it.

API Tools Considered

• Apiary
• Swaggerhub: Platform for documenting APIs with Swagger
• Postman
• ReDoc (source)
• StopLight

Apiary

Sample Usage:

 $.ajax({
   url: "http:private-e7b5b-elisefitzgerald.apiary-mock.com/questions",
   type: 'GET',
   crossDomain: true,
   success: function(data) {
     console.log(data)
   }
 });

Output:

Pros

• Free Tier: Swagger/OpenAPI Editor, Hosted API Documentation, API Mocking
• Connects to Github and auto updates once we start building.
• Mature product
• Collects who has hit out mocked endpoints (could use data to prioritize efforts, etc.)
• Files checked in to Github will auto update docs (and mocks?)- syncing
• Supports versioning and publishing versions separately

Cons

• May need to pay for if we need private access or at least would want to transition to that once we start building
• Written in branded "Blueprint" markdown so amy be little to ramp up

SwaggerHub (...the new Swagger.io)

Sample Usage:

 curl -X GET "https://virtserver.swaggerhub.com/elise-test-acct/test-questions/1.0.0/store/inventory" -H "accept: application/json"

Output:

{
  "id" : 0,
  "category" : {
    "id" : 0,
    "name" : "string"
  },
  "name" : "doggie",
  "photoUrls" : [ "string" ],
  "tags" : [ {
     "id" : 0,
     "name" : "string"
   } ],
  "status" : "available"
}

Pros

• Free Tier: Swagger/OpenAPI Editor, Hosted API Documentation, API Mocking
• Quick documenting: Writing in YAML or JSON
• The Download menu lets you generate server and client code for your API to help you get started with implementation. You can also download your OpenAPI definition as YAML or JSON.
• Supports versioning and publishing versions separately

Cons

• Mock server has 10 req per minute limit

Postman

Documentation view:

Pros

• Full sweet of tools from documentation, mocking server endpoints and testing developed endpoints
• Written in Github markdown, quick ramp up
• Sample requests, headers, and other metadata
• Descriptions associated with requests, folders, and collections
• Generated code snippets in some of the most popular programming languages

Cons

• Free account has rate limits: Only 1000/month free page views of public API documentation, 1000/month mock server requests, Postman API calls
• Doesn't sync with Github on updated docs

ReDoc

Pros

• Open source - we could modify and/or self-host (this is probably also a con, though)
• Built on top of OpenAPI so the documentation we build would be relatively portable

Cons

• No indication of pricing on website (nor a quick way to demo it)
• Hosted solution seems pretty immature (just from the look/feel of their website - lack of live demos/pricing)
• I wonder how many of the reasons for creating this tool have now just been solved upstream in SwaggerHub
• No mock server

StopLight

Pros

• Easy creation of a mock server
• Can import OpenAPI documents
• UI seemed very powerful

Cons

• Would need to pay at least $59/month (free teir is only for internal use - reading between the lines I don't think there would be a read-only link we could give to our partners