search

jfinkels / flask-restless

NO LONGER MAINTAINED - A Flask extension for creating simple ReSTful JSON APIs from SQLAlchemy models.
https://flask-restless.readthedocs.io
GNU Affero General Public License v3.0
1.02k stars 301 forks source link

Feature Request: Documentation Generator #380

Open chaitan94 opened 9 years ago

chaitan94 commented 9 years ago

It's said that "An API is only as good as its documentation", I think the users of flask-restless might benefit a lot if there was an automated documentation generator for their API. Currently in my projects I'm writing my documentations manually, I think this feature could save a lot of time. I've seen issue #206, but not sure how far it has been implemented yet and how effective swagger might be instead of a custom one specific to flask-restless.

ghost commented 9 years ago

:+1:

uSpike commented 9 years ago

You can use sphinxcontrib-httpdomain autodoc for this, but it could be improved.

.. autoflask:: app
   :endpoints:

generates


GET /api/thing/(instid)

    Returns a JSON representation of an instance of model with the specified name.

    If instid is None, this method returns the result of a search with parameters specified in the query string of the request. If no search parameters are specified, this method returns all instances of the specified model.

    If instid is an integer, this method returns the instance of the model with that identifying integer. If no such instance exists, this method responds with :http:status:`404`.

It generates this for each level in /api/thing/(instid)/(relationname)/(relationinstid)

It would be great to be able to override this blueprint doc functionality.

jfinkels commented 9 years ago

I'm not sure that this is in the scope of Flask-Restless. I was going to suggest starting with sphinxcontrib-httpdomain, and modifying that library. Perhaps it might be better suited as a separate extension, Flask-Restless-Docgen, say.

Where do you keep your API documentation? Is it someplace that is automatically discoverable by simply looking at the model? Do you just want to have an automatically generated list of endpoints? If that's the case, you should be able to infer it by looking at the blueprint returned by APIManager.create_api_blueprint.