Remember that users come to your APIs with a mental model of the context you are working in. Some APIs make PUT and PATCH synonymous just be clear on your particular usage. (You can find more info in this StackOverFlow discussion: What is the main difference between PATCH and PUT request?) 2. The documentation for these is unclear (good luck with the RFC), and different apps have different interpretations of them. These are well-established conventions, violate them at your own risk. ![]() The same holds true for HTTP verbs: use POST to create, DELETE to delete. Be consistent! If you can remain consistent in naming conventions and stick with existing standards for behavior, you’ll have to document an item only once … if at all! For example, for HTTP status codes: don’t bend meanings, don’t add new codes: “Don’t force users to understand your slightly eccentric view of the world.” Don’t go off the beaten path: 200 means OK. Good design decisions make it easier to document your APIs. Earned through hard-won experience, here are some tips Andy provided to help you create RESTful API documentation your users will love. It has some basic integration with Sphinx, and some nice features.If APIs are eating the world (as InformationWeek suggests), you can think of API documentation as recipes, a crucial part of making your API easy to understand and easy to use. Just as chefs rely on well-written recipes to create wonderful dishes, you need to create API documentation that is informative, succinct, and easy to read so other developers can cook up something wonderful using your APIs.Īndy Wilkinson, Spring IO Platform lead at cloud-native platform company Pivotal, provided great tips in his presentation “Documenting RESTful APIs” at SpringOne2GX in Washington, D.C., last month. Now, in practice, the last time I checked the project wasn't ready for production. So, you can keep all the goodness of Doxygen and unify the documentation system in Sphinx. The idea is to use Doxygen XML output and feed it to Sphinx to generate your API. Breathe: this started as a very good idea, and makes sense when you work with several related project in other languages that use Doxygen.This is by far the best for automatic API generation in Python (note: shameless self-promotion). ![]() This have been criticized many times and for long we didn't have a good fully automatic Python API generator integrated with Sphinx until AutoAPI came, which is a new kid in the block. My opinion is this tool is good for stub generation that will require manual editing, and nothing more. You have options, but my experience with this approach is that it requires way too much configuration, and at the end even after creating new templates, I found bugs and the impossibility to determine exactly what was exposed as public API and what not. You will require to setup a page with the autosummaries, and then manually edit the pages. You can either setup your build system to call sphinx-autogen or setup your Sphinx with the autosummary_generate config.
0 Comments
Leave a Reply. |