docs: Describe adapters

Author: maxtruxa

docs/docs/adapters.rst

@@ -0,0 +1,36 @@
+==========
+ Adapters
+==========
+
+The *oauth2-server* module is typically not used directly but through one of the available adapters, converting the interface to a suitable one for the HTTP server framework in use.
+
+.. framework-agnostic but there are several officially supported adapters available for popular HTTP server frameworks such as Express_ and Koa_.
+
+- express-oauth-server_ for Express_
+- koa-oauth-server_ for Koa_
+
+.. _express-oauth-server: https://npmjs.org/package/express-oauth-server
+.. _Express: https://npmjs.org/package/express
+.. _koa-oauth-server: https://npmjs.org/package/koa-oauth-server
+.. _Koa: https://npmjs.org/package/koa
+
+
+Writing Adapters
+================
+
+Adapters typically do the following:
+
+- Inherit from :doc:`OAuth2Server </api/oauth2-server>`.
+
+- Override :ref:`authenticate() <OAuth2Server#authenticate>`, :ref:`authorize() <OAuth2Server#authorize>` and :ref:`token() <OAuth2Server#token>`.
+
+  Each of these functions should:
+
+  - Create :doc:`Request </api/request>` and :doc:`Response </api/response>` objects from their framework-specific counterparts.
+
+  - Call the original function.
+
+  - Copy all fields from the :doc:`Response </api/response>` back to the framework-specific request object and send it.
+
+Adapters should preserve functionality provided by *oauth2-server* but are free to add additional features that make sense for the respective HTTP server framework.
+

docs/docs/getting-started.rst

@@ -16,7 +16,7 @@ oauth2-server_ is available via npm_.
 
   $ npm install oauth2-server
 
-.. note:: The *oauth2-server* module is framework-agnostic but there are several officially supported wrappers available for popular HTTP server frameworks such as Express_ and Koa_. If you're using one of those frameworks it is strongly recommended to use the respective wrapper module instead of rolling your own.
+.. note:: The *oauth2-server* module is framework-agnostic but there are several officially supported adapters available for popular HTTP server frameworks such as Express_ and Koa_. If you're using one of those frameworks it is strongly recommended to use the respective adapter module instead of rolling your own.
 
 .. _Express: https://npmjs.org/package/express-oauth-server
 .. _Koa: https://npmjs.org/package/koa-oauth-server

docs/index.rst

@@ -57,6 +57,7 @@ See the :doc:`/model/spec` of what is required from the model passed to :doc:`/a
    :hidden:
 
    docs/getting-started
+   docs/adapters
 
 .. toctree::
    :maxdepth: 2