Learn More
Resend Email
13
kurtr
7y

!Rant

TLDR: What's your favorite REST API Documentation tool?

I'm about to start developing a really large REST API. I have never really had need to document my previous API's since they were small, self explanatory and had only me using them. Aside from this one being too large for me to keep track of there is also a remote team that will need to integrate with it.

Basically I need write exceptional documentation while using as little time as possible. I love postman and am planning to use it for documentation since I currently use it to test during development anyway but I have seen some really neat looking tools like swagger and apiary so I figured I would check for some other suggestions.

What is your current / preferred REST API documentation method?

undefined

api

rest

asking for a friend

suggestions
Favorite
Ranter
Comments
  • 2
    7y
    Have you ever heard of raml ( https://raml.org/ )?
    There are many tools to convert raml to markdown or html pages
  • 1
    7y
    Following
  • 0
    7y
    @Gerschtli I have heard of it, never really looked into it properly but I don't think it's the 'tool' I'm looking for. Might be a future aid though
  • 0
    7y
    I've used apidoc before. I haven't really found anything i really like for rest api documentation but its the closest thing I'm going to find besides writting one myself
  • 1
    7y
    Subscribing
  • 0
    7y
    I'd love to hear recommendations from everyone on this subject. Personally I document all of my API's and one large Word document. So far, I have 300 API's in the document, spanning over 1000 pages. Word for Mac was not designed for such a document. Microsoft sucks!
  • 0
    7y
    How do I subscribe to this thread?
  • 1
    7y
    For all the interested parties: I am definatley going with postman. This awesome walkthrough just unleashed its full potential for me.
    https://sitepoint.com/master-api-wo...

    The biggest bonus is I'm already using postman to test during development!
  • 2
    7y
    /sub
  • 1
    7y
    1. Raml.
    2. Know the API inside out, so you can pull it out anytime for yourself.
  • 0
    7y
    OpenApi, formerly Swagger.
  • 1
    7y
    Depending on the programming language used for the API, you might be able to generate the RAML from code.

    In our Java backend, the documentation, comments, examples etc. are all embedded in decorators besides the method that gets called, e.g.:

    @Method(Method.Post)
    @Path("/customers/:uuid")
    @Description("Creates a new customer")
    @PostBody(UserCreateRequest)
    CreateUser(String uuid) {
    ... actual code ...
    }

    From this data the RAML is then generated which is used for the documentation, for automated front-end client generation, etc.

    It also makes it less tedious to keep implementation and docs in sync, and updates or typo fixes by other non-java developers are just a pull request away.
  • 0
    7y
    Subscribing
Related Rants
devRant © 2021 Hexical Labs LLC
Privacy Policy  |  Terms of Service
Add Comment