search

falconry / falcon

The no-magic web data plane API and microservices framework for Python developers, with a focus on reliability, correctness, and performance at scale.
https://falcon.readthedocs.io/en/stable/
Apache License 2.0
9.51k stars 936 forks source link

Automatically generate homedoc #160

Closed queertypes closed 5 years ago

queertypes commented 11 years ago

It would be pretty awesome if based on routes registered for a Falcon application, Falcon was able to automatically generate a home doc.

More or less like:

api = falcon.API()
...
api.add_route('/v1/health', HealthController())
api.add_route('/v1/obj', ObjectController())
api.add_route('/v1/obj/{obj_id}', ObjectResource())
api.homedoc  # generates home doc as a Python dict
api.homedoc_route('/v1')  # outputs homedoc when user visits /v1

Depends on issue #35

lichray commented 11 years ago

Unfortunately, the params are not covered.

queertypes commented 11 years ago

True... I have an idea on this one, though. If routes were specified using RFC 6570 URI Templates, we might be able to encode parameter requirements. This would take some redesign on Falcon. As a bonus, though, +1 for argument checking and +1 for automatic homedoc.

There's even an implementation of RFC 6570 on pypi - works with Python 2.5+ and Python 3.3.

kgriffs commented 8 years ago

If we do this, we should provide general affordances for generating a variety of API specs. I personally have mixed feelings about letting the code drive the spec, since that means the contract is fluid and prone to implementation errors, but this is something lots of people like to do, so should we support it anyway?

P.S. - I'm open to the idea of supporting the home document proposal out of the box, since it is IMO more in keeping with the spirit of REST than some of the alternatives. But it may be better to just afford this sort of thing and have add-ons in different projects for JSON Home, Swagger, etc.

nZac commented 5 years ago

The home doc RFC is stagnant since 2017, so I don't think we will take it further.