diff --git a/docs/environment.yml b/docs/environment.yml
index 9a4cbf17..1293bb1a 100644
--- a/docs/environment.yml
+++ b/docs/environment.yml
@@ -4,6 +4,7 @@ channels:
 dependencies:
 - nodejs
 - python=3.5
+- alembic
 - jinja2
 - pamela
 - requests
diff --git a/docs/package.json b/docs/package.json
index 04c15c75..5ba8b2b2 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -1,6 +1,6 @@
 {
   "name": "jupyterhub-docs-build",
-  "version": "0.0.0",
+  "version": "0.8.0",
   "description": "build JupyterHub swagger docs",
   "scripts": {
     "rest-api": "bootprint openapi ./rest-api.yml source/_static/rest-api"
@@ -8,7 +8,7 @@
   "author": "",
   "license": "BSD-3-Clause",
   "devDependencies": {
-    "bootprint": "^0.10.0",
-    "bootprint-openapi": "^0.17.0"
+    "bootprint": "^1.0.0",
+    "bootprint-openapi": "^1.0.0"
   }
 }
diff --git a/docs/rest-api.yml b/docs/rest-api.yml
index 283ae078..8fa65c40 100644
--- a/docs/rest-api.yml
+++ b/docs/rest-api.yml
@@ -424,9 +424,6 @@ paths:
       responses:
         '200':
           description: The user or service identified by the API token
-          schema:
-            $ref: '#/definitions/User'
-            $ref: '#/definitions/Service'
         '404':
           description: A user or service is not found.
   /authorizations/cookie/{cookie_name}/{cookie_value}:
diff --git a/docs/source/api/app.rst b/docs/source/api/app.rst
index 6eadb729..f2289a24 100644
--- a/docs/source/api/app.rst
+++ b/docs/source/api/app.rst
@@ -2,9 +2,15 @@
 Application configuration
 =========================
 
+Module: :mod:`jupyterhub.app`
+=============================
+
+.. automodule:: jupyterhub.app
+
 .. currentmodule:: jupyterhub.app
 
 :class:`JupyterHub`
 -------------------
 
 .. autoconfigurable:: JupyterHub
+
diff --git a/docs/source/api/auth.rst b/docs/source/api/auth.rst
index f2a99bc2..39d0e791 100644
--- a/docs/source/api/auth.rst
+++ b/docs/source/api/auth.rst
@@ -9,13 +9,20 @@ Module: :mod:`jupyterhub.auth`
 
 .. currentmodule:: jupyterhub.auth
 
-
+:class:`Authenticator`
+----------------------
 
 .. autoconfigurable:: Authenticator
     :members:
 
+:class:`LocalAuthenticator`
+---------------------------
+
 .. autoconfigurable:: LocalAuthenticator
     :members:
 
+:class:`PAMAuthenticator`
+-------------------------
+
 .. autoconfigurable:: PAMAuthenticator
 
diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst
index a354e939..cfbfcb17 100644
--- a/docs/source/api/index.rst
+++ b/docs/source/api/index.rst
@@ -1,8 +1,8 @@
 .. _api-index:
 
-####################
- The JupyterHub API
-####################
+##################
+The JupyterHub API
+##################
 
 :Release: |release|
 :Date: |today|
@@ -31,6 +31,7 @@ JupyterHub API Reference:
     spawner
     proxy
     user
+    service
     services.auth
 
 
diff --git a/docs/source/api/proxy.rst b/docs/source/api/proxy.rst
index 49bf4048..426860d1 100644
--- a/docs/source/api/proxy.rst
+++ b/docs/source/api/proxy.rst
@@ -9,11 +9,15 @@ Module: :mod:`jupyterhub.proxy`
 
 .. currentmodule:: jupyterhub.proxy
 
-
+:class:`Proxy`
+--------------
 
 .. autoconfigurable:: Proxy
     :members:
 
+:class:`ConfigurableHTTPProxy`
+------------------------------
+
 .. autoconfigurable:: ConfigurableHTTPProxy
     :members: debug, auth_token, check_running_interval, api_url, command
 
diff --git a/docs/source/api/service.rst b/docs/source/api/service.rst
new file mode 100644
index 00000000..e4044b90
--- /dev/null
+++ b/docs/source/api/service.rst
@@ -0,0 +1,17 @@
+========
+Services
+========
+
+Module: :mod:`jupyterhub.services.service`
+==========================================
+
+.. automodule:: jupyterhub.services.service
+
+.. currentmodule:: jupyterhub.services.service
+
+:class:`Service`
+----------------
+
+.. autoconfigurable:: Service
+    :members: name, admin, url, api_token, managed, kind, command, cwd, environment, user, oauth_client_id, server, prefix, proxy_spec
+
diff --git a/docs/source/api/services.auth.rst b/docs/source/api/services.auth.rst
index 38059d08..1fe4c3f6 100644
--- a/docs/source/api/services.auth.rst
+++ b/docs/source/api/services.auth.rst
@@ -1,5 +1,5 @@
 =======================
-Authenticating Services
+Services Authentication
 =======================
 
 Module: :mod:`jupyterhub.services.auth`
@@ -10,9 +10,16 @@ Module: :mod:`jupyterhub.services.auth`
 .. currentmodule:: jupyterhub.services.auth
 
 
+:class:`HubAuth`
+----------------
+
 .. autoconfigurable:: HubAuth
     :members:
 
+
+:class:`HubAuthenticated`
+-------------------------
+
 .. autoclass:: HubAuthenticated
     :members:
 
diff --git a/docs/source/api/spawner.rst b/docs/source/api/spawner.rst
index e6c7f56a..3c564c0e 100644
--- a/docs/source/api/spawner.rst
+++ b/docs/source/api/spawner.rst
@@ -1,6 +1,6 @@
-==============
-   Spawners
-==============
+========
+Spawners
+========
 
 Module: :mod:`jupyterhub.spawner`
 =================================
@@ -15,4 +15,8 @@ Module: :mod:`jupyterhub.spawner`
 .. autoconfigurable:: Spawner
     :members: options_from_form, poll, start, stop, get_args, get_env, get_state, template_namespace, format_string
 
+:class:`LocalProcessSpawner`
+----------------------------
+
 .. autoconfigurable:: LocalProcessSpawner
+
diff --git a/docs/source/api/user.rst b/docs/source/api/user.rst
index 2e7b31cf..2a84bad6 100644
--- a/docs/source/api/user.rst
+++ b/docs/source/api/user.rst
@@ -1,6 +1,6 @@
-=============
-   Users
-=============
+=====
+Users
+=====
 
 Module: :mod:`jupyterhub.user`
 ==============================
@@ -9,11 +9,16 @@ Module: :mod:`jupyterhub.user`
 
 .. currentmodule:: jupyterhub.user
 
+:class:`UserDict`
+-----------------
+
+.. autoclass:: UserDict
+    :members:
+
+
 :class:`User`
 -------------
 
-.. class:: Server
-
 .. autoclass:: User
     :members: escaped_name
     
@@ -29,3 +34,4 @@ Module: :mod:`jupyterhub.user`
     .. attribute:: spawner
     
         The user's :class:`~.Spawner` instance.
+
diff --git a/jupyterhub/services/auth.py b/jupyterhub/services/auth.py
index 9d437d19..cca6f094 100644
--- a/jupyterhub/services/auth.py
+++ b/jupyterhub/services/auth.py
@@ -1,12 +1,14 @@
-"""Authenticating services with JupyterHub
+"""Authenticating services with JupyterHub.
 
-Cookies are sent to the Hub for verification, replying with a JSON model describing the authenticated user.
+Cookies are sent to the Hub for verification. The Hub replies with a JSON
+model describing the authenticated user.
 
-HubAuth can be used in any application, even outside tornado.
+``HubAuth`` can be used in any application, even outside tornado.
+
+``HubAuthenticated`` is a mixin class for tornado handlers that should
+authenticate with the Hub.
 
-HubAuthenticated is a mixin class for tornado handlers that should authenticate with the Hub.
 """
-
 import os
 import re
 import socket
diff --git a/jupyterhub/services/service.py b/jupyterhub/services/service.py
index 4df13e04..29cafdc6 100644
--- a/jupyterhub/services/service.py
+++ b/jupyterhub/services/service.py
@@ -1,15 +1,14 @@
-"""A service is a process that talks to JupyterHub
+"""A service is a process that talks to JupyterHub.
 
-Cases:
-
-Managed:
-  - managed by JupyterHub (always subprocess, no custom Spawners)
-  - always a long-running process
-  - managed services are restarted automatically if they exit unexpectedly
-Unmanaged:
-  - managed by external service (docker, systemd, etc.)
-  - do not need to be long-running processes, or processes at all
+Types of services:
+    Managed:
+      - managed by JupyterHub (always subprocess, no custom Spawners)
+      - always a long-running process
+      - managed services are restarted automatically if they exit unexpectedly
 
+    Unmanaged:
+      - managed by external service (docker, systemd, etc.)
+      - do not need to be long-running processes, or processes at all
 
 URL: needs a route added to the proxy.
   - Public route will always be /services/service-name
@@ -30,13 +29,14 @@ An externally managed service running on a URL::
         'api_token': 'super-secret',
     }
 
-A hub-managed service with no URL:
+A hub-managed service with no URL::
 
     {
         'name': 'cull-idle',
         'command': ['python', '/path/to/cull-idle']
         'admin': True,
     }
+
 """
 
 import pipes