From d5e734f8e2e680399a9676a706b89da39f7ad35c Mon Sep 17 00:00:00 2001 From: wvengen Date: Sat, 28 May 2016 16:26:19 +0200 Subject: [PATCH] Update API documentation --- doc/API.md | 25 +++++++++++++++++++------ doc/swagger.v1.yml | 18 +++++++++++++++++- 2 files changed, 36 insertions(+), 7 deletions(-) diff --git a/doc/API.md b/doc/API.md index 93763b68a8..7812442309 100644 --- a/doc/API.md +++ b/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). - diff --git a/doc/swagger.v1.yml b/doc/swagger.v1.yml index 4ab93e5f0d..1885bbc1af 100644 --- a/doc/swagger.v1.yml +++ b/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