Update API documentation

doc/API.md

@@ -1,13 +1,27 @@
 # Foodsoft API
 
+Foodsoft currently provides a JSON REST API that gives access to _member_ operations
+like listing open orders, updating the ordergroup's order, and listing financial
+transactions. (Later versions of the API might include admin-related functionality.)
 
-## Endpoints
+The API is documented using [Open API 2.0](https://github.com/OAI/OpenAPI-Specification)
+/ [Swagger](http://swagger.io/) in [swagger.v1.yml](swagger.v1.yml).
+This provides a machine-readable reference that is used for
+[running tests](https://github.com/westfieldlabs/apivore) and providing documentation.
 
-### /:scope/api/v1/financial_transactions
+## API endpoint documentation
 
-### /:scope/api/v1/orders
+>> [View API documentation](http://petstore.swagger.io/?http%3A%2F%2Fcdn.rawgit.com%2Ffoodcoops%2Ffoodsoft%2Fmaster%2Fdoc%2Fswagger.v1.yml) <<
 
-### /:scope/api/v1/article_categories
+The above documentation can communicate with the API directly on a local development
+installation of Foodsoft at [http://localhost:3000/f](http://localhost:3000/f). You'll need
+to give access to the application by running in the rails console
+
+```ruby
+app = Doorkeeper::Application.new
+app.name = 'Swagger'; app.scopes = 'all'; app.uid = 'your-client-id'; app.redirect_uri = 'http://petstore.swagger.io/o2c.html'
+app.save!
+```
 
 
 ## Security
@@ -50,7 +64,7 @@ You only need the client_id though, not the secret.
 
 **note** please make sure you understand sections
 [4.4.2](http://tools.ietf.org/html/rfc6819#section-4.4.2) and
-[4.4.3](http://tools.ietf.org/html/rfc6819#section-4.4.3) of the OAuth2 Thread
+[4.4.3](http://tools.ietf.org/html/rfc6819#section-4.4.3) of the OAuth2 Threat
 Model document before using this flow.
 
 You may find Doorkeeper's [implicit_grant_test](https://github.com/doorkeeper-gem/doorkeeper/blob/master/spec/requests/flows/implicit_grant_spec.rb) useful.
@@ -72,4 +86,3 @@ Now use this token as value for the `access_token` when accessing the API, like
 http://localhost:3002/f/api/v1/financial_transactions/1?access_token=12345...
 
 [Read more](https://github.com/doorkeeper-gem/doorkeeper/wiki/Client-Credentials-flow).
-

doc/swagger.v1.yml

@@ -2,9 +2,25 @@ swagger: '2.0'
 info:
   title: Foodsoft API v1
   version: '1.0.0'
+  description: |-
+    [Foodsoft](https://github.com/foodcoops/foodsoft) is web-based software to manage
+    a non-profit food coop (product catalog, ordering, accounting, job scheduling).
+
+    This is a description of Foodsoft's API v1, which exposes operations that a member
+    can do (later API versions may include admin functionality). It includes listing
+    open orders, and changing what the member wants to order (in the ordergroup).
+
+    Note that each food cooperative typically has their own instance (on a shared
+    server or their own installation), and there are just as many APIs (if the Foodsoft
+    version is recent enough).
+    This API description points to the default development url with the default
+    Foodsoft scope - that would be [http://localhost:3000/f](http://localhost:3000/f).
+externalDocs:
+  description: General Foodsoft API documentation
+  url: https://github.com/foodcoops/foodsoft/blob/master/doc/API.md
 
 # development url with default scope
-host: localhost:3002
+host: localhost:3000
 schemes:
   - 'http'
 basePath: /f/api/v1