Ranter
Join devRant
Do all the things like
++ or -- rants, post your own rants, comment on others' rants and build your customized dev avatar
Sign Up
Pipeless API
From the creators of devRant, Pipeless lets you power real-time personalized recommendations and activity feeds using a simple API
Learn More
Comments
-
Gerschtli517yHave you ever heard of raml ( https://raml.org/ )?
There are many tools to convert raml to markdown or html pages -
kurtr127547y@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
-
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
-
BM3224537yI'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!
-
kurtr127547yFor 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! -
hawkes15727yDepending 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.
Related Rants
!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