Restful Web Services api documentation tool

Question

Before during, and even after Web Services implementation, an up-to-date user guide is very important to our customers. I am trying to find an API tool for Restful Web Services which can produce a user-friendly document / user guide in either WORD or PDF format. Is there any suggestions?

Key points include:

• Documenting APIs
• Basic information on API (current user guide)
• How to use APIs
• Test APIs before implementation

Answer 1

Have you tried apidocjs ?

• Documenting APIs

  Well, it quite easy, because what we need to do is just commenting on our code. This is an example.

  /**
   * @api {get} /user/:id Request User information
   * @apiName GetUser
   * @apiGroup User
   *
   * @apiParam {Number} id Users unique ID.
   *
   * @apiSuccess {String} firstname Firstname of the User.
   * @apiSuccess {String} lastname  Lastname of the User.
   */
  

  Example on Lumen Framework, you can put the comment on Controllers app/Http/Controllers/UserController@create. @ refer to function inside the controller.

  Use this command to generate the doc

  apidoc -i app/Http/Controllers -o public/docs

• Basic information on API (current user guide)

  Yes, please go to apidocjs example.

• How to use APIs

  See above example.

• Test APIs before implementation

  It has an interesting feature, check @apiSampleRequest. But if you mean Test is Unit Testing or Functional Testing, apidocjs not support.