Repository: deis/deis

Issue:
API Documents do not include request/response data
As referenced in #1488 , the API docs currently cover only the RESTful URLs, but do not cover the data schemas being sent to or from the end point.  



Discussion:
This is certainly something that I'm interested in seeing as well :thumbsup:.

Will look into documenting the API as I go along with #1042.


Resolving patch:
diff --git a/controller/api/urls.py b/controller/api/urls.py
--- a/controller/api/urls.py
+++ b/controller/api/urls.py
@@ -1,204 +1,3 @@
-"""
-RESTful URL patterns and routing for the Deis API app.
-
-
-Applications
-============
-
-.. http:get:: /v1/apps/(string:id)/
-
-  Retrieve a :class:`~api.models.App` by its `id`.
-
-.. http:delete:: /v1/apps/(string:id)/
-
-  Destroy a :class:`~api.models.App` by its `id`.
-
-.. http:get:: /v1/apps/
-
-  List all :class:`~api.models.App`\s.
-
-.. http:post:: /v1/apps/
-
-  Create a new :class:`~api.models.App`.
-
-
-Application Release Components
-------------------------------
-
-.. http:get:: /v1/apps/(string:id)/config/
-
-  List all :class:`~api.models.Config`\s.
-
-.. http:post:: /v1/apps/(string:id)/config/
-
-  Create a new :class:`~api.models.Config`.
-
-.. http:get:: /v1/apps/(string:id)/builds/(string:uuid)/
-
-  Retrieve a :class:`~api.models.Build` by its `uuid`.
-
-.. http:get:: /v1/apps/(string:id)/builds/
-
-  List all :class:`~api.models.Build`\s.
-
-.. http:post:: /v1/apps/(string:id)/builds/
-
-  Create a new :class:`~api.models.Build`.
-
-.. http:get:: /v1/apps/(string:id)/releases/(int:version)/
-
-  Retrieve a :class:`~api.models.Release` by its `version`.
-
-.. http:get:: /v1/apps/(string:id)/releases/
-
-  List all :class:`~api.models.Release`\s.
-
-.. http:post:: /v1/apps/(string:id)/releases/rollback/
-
-  Rollback to a previous :class:`~api.models.Release`.
-
-
-Application Infrastructure
---------------------------
-
-.. http:get:: /v1/apps/(string:id)/containers/(string:type)/(int:num)/
-
-  List all :class:`~api.models.Container`\s.
-
-.. http:get:: /v1/apps/(string:id)/containers/(string:type)/
-
-  List all :class:`~api.models.Container`\s.
-
-.. http:get:: /v1/apps/(string:id)/containers/
-
-  List all :class:`~api.models.Container`\s.
-
-
-Application Domains
--------------------
-
-
-.. http:delete:: /v1/apps/(string:id)/domains/(string:hostname)
-
-  Destroy a :class:`~api.models.Domain` by its `hostname`
-
-.. http:get:: /v1/apps/(string:id)/domains/
-
-  List all :class:`~api.models.Domain`\s.
-
-.. http:post:: /v1/apps/(string:id)/domains/
-
-  Create a new :class:`~api.models.Domain`\s.
-
-
-Application Actions
--------------------
-
-.. http:post:: /v1/apps/(string:id)/scale/
-
-  See also
-  :meth:`AppViewSet.scale() <api.views.AppViewSet.scale>`
-
-.. http:get:: /v1/apps/(string:id)/logs/
-
-  See also
-  :meth:`AppViewSet.logs() <api.views.AppViewSet.logs>`
-
-.. http:post:: /v1/apps/(string:id)/run/
-
-  See also
-  :meth:`AppViewSet.run() <api.views.AppViewSet.run>`
-
-
-Application Sharing
-===================
-
-.. http:delete:: /v1/apps/(string:id)/perms/(string:username)/
-
-  Destroy an app permission by its `username`.
-
-.. http:get:: /v1/apps/(string:id)/perms/
-
-  List all permissions granted to this app.
-
-.. http:post:: /v1/apps/(string:id)/perms/
-
-  Create a new app permission.
-
-
-Keys
-====
-
-.. http:get:: /v1/keys/(string:id)/
-
-  Retrieve a :class:`~api.models.Key` by its `id`.
-
-.. http:delete:: /v1/keys/(string:id)/
-
-  Destroy a :class:`~api.models.Key` by its `id`.
-
-.. http:get:: /v1/keys/
-
-  List all :class:`~api.models.Key`\s.
-
-.. http:post:: /v1/keys/
-
-  Create a new :class:`~api.models.Key`.
-
-
-API Hooks
-=========
-
-.. http:post:: /v1/hooks/push/
-
-  Create a new :class:`~api.models.Push`.
-
-.. http:post:: /v1/hooks/build/
-
-  Create a new :class:`~api.models.Build`.
-
-.. http:post:: /v1/hooks/config/
-
-  Retrieve latest application :class:`~api.models.Config`.
-
-
-Auth
-====
-
-.. http:post:: /v1/auth/register/
-
-  Create a new User.
-
-.. http:delete:: /v1/auth/cancel/
-
-  Destroy the logged-in User.
-
-.. http:post:: /v1/auth/passwd/
-
-  Update the password of the logged-in User.
-
-.. http:get:: /v1/auth/login/
-
-  Generate an API key.
-
-
-Admin Sharing
-=============
-
-.. http:delete:: /v1/admin/perms/(string:username)/
-
-  Destroy an admin permission by its `username`.
-
-.. http:get:: /v1/admin/perms/
-
-  List all admin permissions granted.
-
-.. http:post:: /v1/admin/perms/
-
-  Create a new admin permission.
-
-"""
-
 from __future__ import unicode_literals
 
 from django.conf import settings
diff --git a/docs/conf.py b/docs/conf.py
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -40,7 +40,7 @@
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary',
-              'sphinx.ext.viewcode', 'sphinxcontrib.httpdomain']
+              'sphinx.ext.viewcode']
 
 # default flags for auto-generated python code documetation
 autodoc_default_flags = ['members', 'undoc-members']


Test patch: