Dokumentasi RESTful API dengan Sphinx

blog Mei 06, 2017

Dalam penulisan dokumentasi dengan Sphinx biasanya ada ekstensi tambahan untuk memudahkan penyusunan dokumen. Salah satunya adalah ekstensi httpdomain

Ekstensi httpdomain dibuat untuk membantu penyusunan dokumentasi RESTful HTTP API.


pip install sphinxcontrib-httpdomain


Di file sphinx bagian extension tambahkan:

extensions = ['sphinxcontrib.httpdomain']

Contoh penggunaan

.. http:get:: /users/(int:user_id)/posts/(tag)

   The posts tagged with `tag` that the user (`user_id`) wrote.

   **Example request**:

   .. sourcecode:: http

      GET /users/123/posts/web HTTP/1.1
      Accept: application/json, text/javascript

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Vary: Accept
      Content-Type: text/javascript

          "post_id": 12345,
          "author_id": 123,
          "tags": ["server", "web"],
          "subject": "I tried Nginx"
          "post_id": 12346,
          "author_id": 123,
          "tags": ["html5", "standards", "web"],
          "subject": "We go to HTML 5"

   :query sort: one of ``hit``, ``created-at``
   :query offset: offset number. default is 0
   :query limit: limit number. default is 30
   :reqheader Accept: the response content type depends on
                      :mailheader:`Accept` header
   :reqheader Authorization: optional OAuth token to authenticate
   :resheader Content-Type: this depends on :mailheader:`Accept`
                            header of request
   :statuscode 200: no error
   :statuscode 404: there's no user