mirror of
https://github.com/encode/django-rest-framework.git
synced 2024-11-15 06:07:41 +03:00
495 lines
21 KiB
HTML
495 lines
21 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
|
<meta charset="utf-8">
|
|
<title>Documenting your API - Django REST framework</title>
|
|
<link href="../../img/favicon.ico" rel="icon" type="image/x-icon">
|
|
<link rel="canonical" href="http://www.django-rest-framework.org/topics/documenting-your-api/" />
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<meta name="description" content="Django, API, REST, Documenting your API">
|
|
<meta name="author" content="Tom Christie">
|
|
|
|
<!-- Le styles -->
|
|
<link href="../../css/prettify.css" rel="stylesheet">
|
|
<link href="../../css/bootstrap.css" rel="stylesheet">
|
|
<link href="../../css/bootstrap-responsive.css" rel="stylesheet">
|
|
<link href="../../css/default.css" rel="stylesheet">
|
|
|
|
<!-- Le HTML5 shim, for IE6-8 support of HTML5 elements -->
|
|
<!--[if lt IE 9]>
|
|
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
|
|
<![endif]-->
|
|
|
|
<script type="text/javascript">
|
|
var _gaq = _gaq || [];
|
|
_gaq.push(['_setAccount', 'UA-18852272-2']);
|
|
_gaq.push(['_trackPageview']);
|
|
|
|
(function() {
|
|
var ga = document.createElement('script');
|
|
ga.type = 'text/javascript';
|
|
ga.async = true;
|
|
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
|
|
var s = document.getElementsByTagName('script')[0];
|
|
s.parentNode.insertBefore(ga, s);
|
|
})();
|
|
</script>
|
|
|
|
<style>
|
|
span.fusion-wrap a {
|
|
display: block;
|
|
margin-top: 10px;
|
|
color: black;
|
|
}
|
|
a.fusion-poweredby {
|
|
display: block;
|
|
margin-top: 10px;
|
|
}
|
|
@media (max-width: 767px) {
|
|
div.promo {
|
|
display: none;
|
|
}
|
|
}
|
|
</style>
|
|
</head>
|
|
<body onload="prettyPrint()" class="-page">
|
|
|
|
<div class="wrapper">
|
|
|
|
<div class="navbar navbar-inverse navbar-fixed-top">
|
|
<div class="navbar-inner">
|
|
<div class="container-fluid">
|
|
<a class="repo-link btn btn-primary btn-small" href="https://github.com/tomchristie/django-rest-framework/tree/master">GitHub</a>
|
|
<a class="repo-link btn btn-inverse btn-small " rel="prev" href="../ajax-csrf-cors">
|
|
Next <i class="icon-arrow-right icon-white"></i>
|
|
</a>
|
|
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../../api-guide/settings">
|
|
<i class="icon-arrow-left icon-white"></i> Previous
|
|
</a>
|
|
<a class="repo-link btn btn-inverse btn-small" href="#searchModal" data-toggle="modal"><i class="icon-search icon-white"></i> Search</a>
|
|
<a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
|
|
<span class="icon-bar"></span>
|
|
<span class="icon-bar"></span>
|
|
<span class="icon-bar"></span>
|
|
</a>
|
|
<a class="brand" href="http://www.django-rest-framework.org">Django REST framework</a>
|
|
<div class="nav-collapse collapse">
|
|
|
|
<!-- Main navigation -->
|
|
<ul class="nav navbar-nav">
|
|
<li ><a href="/">Home</a></li>
|
|
|
|
<li class="dropdown">
|
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorial <b class="caret"></b></a>
|
|
<ul class="dropdown-menu">
|
|
|
|
<li >
|
|
<a href="../../tutorial/quickstart">Quickstart</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../tutorial/1-serialization">1 - Serialization</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../tutorial/2-requests-and-responses">2 - Requests and responses</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../tutorial/3-class-based-views">3 - Class based views</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../tutorial/4-authentication-and-permissions">4 - Authentication and permissions</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../tutorial/5-relationships-and-hyperlinked-apis">5 - Relationships and hyperlinked APIs</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../tutorial/6-viewsets-and-routers">6 - Viewsets and routers</a>
|
|
</li>
|
|
|
|
</ul>
|
|
</li>
|
|
|
|
<li class="dropdown">
|
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Guide <b class="caret"></b></a>
|
|
<ul class="dropdown-menu">
|
|
|
|
<li >
|
|
<a href="../../api-guide/requests">Requests</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/responses">Responses</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/views">Views</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/generic-views">Generic views</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/viewsets">Viewsets</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/routers">Routers</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/parsers">Parsers</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/renderers">Renderers</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/serializers">Serializers</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/fields">Serializer fields</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/relations">Serializer relations</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/validators">Validators</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/authentication">Authentication</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/permissions">Permissions</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/throttling">Throttling</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/filtering">Filtering</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/pagination">Pagination</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/content-negotiation">Content negotiation</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/metadata">Metadata</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/format-suffixes">Format suffixes</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/reverse">Returning URLs</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/exceptions">Exceptions</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/status-codes">Status codes</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/testing">Testing</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/settings">Settings</a>
|
|
</li>
|
|
|
|
</ul>
|
|
</li>
|
|
|
|
<li class="dropdown active">
|
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Topics <b class="caret"></b></a>
|
|
<ul class="dropdown-menu">
|
|
|
|
<li class="active" >
|
|
<a href=".">Documenting your API</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../ajax-csrf-cors">AJAX, CSRF & CORS</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../browser-enhancements">Browser enhancements</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../browsable-api">The Browsable API</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../third-party-resources">Third Party Resources</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../contributing">Contributing to REST framework</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../project-management">Project management</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../rest-framework-2-announcement">2.0 Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../2.2-announcement">2.2 Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../2.3-announcement">2.3 Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../2.4-announcement">2.4 Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../3.0-announcement">3.0 Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../kickstarter-announcement">Kickstarter Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../release-notes">Release Notes</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../credits">Credits</a>
|
|
</li>
|
|
|
|
</ul>
|
|
</li>
|
|
|
|
|
|
</ul>
|
|
|
|
</div>
|
|
<!--/.nav-collapse -->
|
|
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="body-content">
|
|
<div class="container-fluid">
|
|
|
|
<!-- Search Modal -->
|
|
<div id="searchModal" class="modal hide fade" tabindex="-1" role="dialog" aria-labelledby="myModalLabel" aria-hidden="true">
|
|
<div class="modal-header">
|
|
<button type="button" class="close" data-dismiss="modal" aria-hidden="true">×</button>
|
|
<h3 id="myModalLabel">Documentation search</h3>
|
|
</div>
|
|
|
|
<div class="modal-body">
|
|
<!-- Custom google search -->
|
|
<script>
|
|
(function() {
|
|
var cx = '015016005043623903336:rxraeohqk6w';
|
|
var gcse = document.createElement('script');
|
|
gcse.type = 'text/javascript';
|
|
gcse.async = true;
|
|
gcse.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') +
|
|
'//www.google.com/cse/cse.js?cx=' + cx;
|
|
var s = document.getElementsByTagName('script')[0];
|
|
s.parentNode.insertBefore(gcse, s);
|
|
})();
|
|
</script>
|
|
<gcse:search></gcse:search>
|
|
</div>
|
|
|
|
<div class="modal-footer">
|
|
<button class="btn" data-dismiss="modal" aria-hidden="true">Close</button>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="row-fluid">
|
|
|
|
<div class="span3">
|
|
<!-- TODO
|
|
<p style="margin-top: -12px">
|
|
<a class="btn btn-mini btn-primary" style="width: 60px">« previous</a>
|
|
<a class="btn btn-mini btn-primary" style="float: right; margin-right: 8px; width: 60px;">next »</a>
|
|
</p>
|
|
-->
|
|
<div id="table-of-contents">
|
|
<ul class="nav nav-list side-nav well sidebar-nav-fixed">
|
|
|
|
|
|
|
|
|
|
|
|
<li class="main">
|
|
<a href="#documenting-your-api">Documenting your API</a>
|
|
</li>
|
|
|
|
|
|
<li>
|
|
<a href="#endpoint-documentation">Endpoint documentation</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#self-describing-apis">Self describing APIs</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#the-hypermedia-approach">The hypermedia approach</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</ul>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div id="main-content" class="span9">
|
|
|
|
|
|
<h1 id="documenting-your-api">Documenting your API</h1>
|
|
<blockquote>
|
|
<p>A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state.</p>
|
|
<p>— Roy Fielding, <a href="http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven">REST APIs must be hypertext driven</a></p>
|
|
</blockquote>
|
|
<p>There are a variety of approaches to API documentation. This document introduces a few of the various tools and options you might choose from. The approaches should not be considered exclusive - you may want to provide more than one documentation style for you API, such as a self describing API that also includes static documentation of the various API endpoints.</p>
|
|
<h2 id="endpoint-documentation">Endpoint documentation</h2>
|
|
<p>The most common way to document Web APIs today is to produce documentation that lists the API endpoints verbatim, and describes the allowable operations on each. There are various tools that allow you to do this in an automated or semi-automated way.</p>
|
|
<hr />
|
|
<h4 id="django-rest-swagger">Django REST Swagger</h4>
|
|
<p>Marc Gibbons' <a href="https://github.com/marcgibbons/django-rest-swagger">Django REST Swagger</a> integrates REST framework with the <a href="https://developers.helloreverb.com/swagger/">Swagger</a> API documentation tool. The package produces well presented API documentation, and includes interactive tools for testing API endpoints.</p>
|
|
<p>The package is fully documented, well supported, and comes highly recommended.</p>
|
|
<p>Django REST Swagger supports REST framework versions 2.3 and above.</p>
|
|
<p><img alt="Screenshot - Django REST Swagger" src="../../../img/django-rest-swagger.png" /></p>
|
|
<hr />
|
|
<h4 id="rest-framework-docs">REST Framework Docs</h4>
|
|
<p>The <a href="https://github.com/marcgibbons/django-rest-framework-docs">REST Framework Docs</a> package is an earlier project, also by Marc Gibbons, that offers clean, simple autogenerated documentation for your API.</p>
|
|
<p><img alt="Screenshot - REST Framework Docs" src="../../../img/rest-framework-docs.png" /></p>
|
|
<hr />
|
|
<h4 id="apiary">Apiary</h4>
|
|
<p>There are various other online tools and services for providing API documentation. One notable service is <a href="http://apiary.io/">Apiary</a>. With Apiary, you describe your API using a simple markdown-like syntax. The generated documentation includes API interaction, a mock server for testing & prototyping, and various other tools.</p>
|
|
<p><img alt="Screenshot - Apiary" src="../../../img/apiary.png" /></p>
|
|
<hr />
|
|
<h2 id="self-describing-apis">Self describing APIs</h2>
|
|
<p>The browsable API that REST framework provides makes it possible for your API to be entirely self describing. The documentation for each API endpoint can be provided simply by visiting the URL in your browser.</p>
|
|
<p><img alt="Screenshot - Self describing API" src="../../../img/self-describing.png" /></p>
|
|
<hr />
|
|
<h4 id="setting-the-title">Setting the title</h4>
|
|
<p>The title that is used in the browsable API is generated from the view class name or function name. Any trailing <code>View</code> or <code>ViewSet</code> suffix is stripped, and the string is whitespace separated on uppercase/lowercase boundaries or underscores.</p>
|
|
<p>For example, the view <code>UserListView</code>, will be named <code>User List</code> when presented in the browsable API.</p>
|
|
<p>When working with viewsets, an appropriate suffix is appended to each generated view. For example, the view set <code>UserViewSet</code> will generate views named <code>User List</code> and <code>User Instance</code>.</p>
|
|
<h4 id="setting-the-description">Setting the description</h4>
|
|
<p>The description in the browsable API is generated from the docstring of the view or viewset.</p>
|
|
<p>If the python <code>markdown</code> library is installed, then <a href="http://daringfireball.net/projects/markdown/">markdown syntax</a> may be used in the docstring, and will be converted to HTML in the browsable API. For example:</p>
|
|
<pre><code>class AccountListView(views.APIView):
|
|
"""
|
|
Returns a list of all **active** accounts in the system.
|
|
|
|
For more details on how accounts are activated please [see here][ref].
|
|
|
|
[ref]: http://example.com/activating-accounts
|
|
"""
|
|
</code></pre>
|
|
<p>Note that one constraint of using viewsets is that any documentation be used for all generated views, so for example, you cannot have differing documentation for the generated list view and detail view.</p>
|
|
<h4 id="the-options-method">The <code>OPTIONS</code> method</h4>
|
|
<p>REST framework APIs also support programmatically accessible descriptions, using the <code>OPTIONS</code> HTTP method. A view will respond to an <code>OPTIONS</code> request with metadata including the name, description, and the various media types it accepts and responds with.</p>
|
|
<p>When using the generic views, any <code>OPTIONS</code> requests will additionally respond with metadata regarding any <code>POST</code> or <code>PUT</code> actions available, describing which fields are on the serializer.</p>
|
|
<p>You can modify the response behavior to <code>OPTIONS</code> requests by overriding the <code>metadata</code> view method. For example:</p>
|
|
<pre><code>def metadata(self, request):
|
|
"""
|
|
Don't include the view description in OPTIONS responses.
|
|
"""
|
|
data = super(ExampleView, self).metadata(request)
|
|
data.pop('description')
|
|
return data
|
|
</code></pre>
|
|
<hr />
|
|
<h2 id="the-hypermedia-approach">The hypermedia approach</h2>
|
|
<p>To be fully RESTful an API should present its available actions as hypermedia controls in the responses that it sends.</p>
|
|
<p>In this approach, rather than documenting the available API endpoints up front, the description instead concentrates on the <em>media types</em> that are used. The available actions that may be taken on any given URL are not strictly fixed, but are instead made available by the presence of link and form controls in the returned document.</p>
|
|
<p>To implement a hypermedia API you'll need to decide on an appropriate media type for the API, and implement a custom renderer and parser for that media type. The <a href="../rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a> section of the documentation includes pointers to background reading, as well as links to various hypermedia formats.</p>
|
|
|
|
</div>
|
|
<!--/span-->
|
|
</div>
|
|
<!--/row-->
|
|
</div>
|
|
<!--/.fluid-container-->
|
|
</div>
|
|
<!--/.body content-->
|
|
<div id="push"></div>
|
|
</div>
|
|
<!--/.wrapper -->
|
|
|
|
<footer class="span12">
|
|
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
|
|
</p>
|
|
</footer>
|
|
|
|
<!-- Le javascript
|
|
================================================== -->
|
|
<!-- Placed at the end of the document so the pages load faster -->
|
|
<script src="../../js/jquery-1.8.1-min.js"></script>
|
|
<script src="../../js/prettify-1.0.js"></script>
|
|
<script src="../../js/bootstrap-2.1.1-min.js"></script>
|
|
<script src="../../js/theme.js"></script>
|
|
|
|
<script>
|
|
//$('.side-nav').scrollspy()
|
|
var shiftWindow = function() {
|
|
scrollBy(0, -50)
|
|
};
|
|
if (location.hash) shiftWindow();
|
|
window.addEventListener("hashchange", shiftWindow);
|
|
|
|
$('.dropdown-menu').on('click touchstart', function(event) {
|
|
event.stopPropagation();
|
|
});
|
|
|
|
// Dynamically force sidenav to no higher than browser window
|
|
$('.side-nav').css('max-height', window.innerHeight - 130);
|
|
|
|
$(function() {
|
|
$(window).resize(function() {
|
|
$('.side-nav').css('max-height', window.innerHeight - 130);
|
|
});
|
|
});
|
|
</script>
|
|
</body>
|
|
|
|
</html> |