Merge pull request laravel#40 from eurides-eu/feature/add-authentication-docs

Feature/add authentication docs

Author: dieterve

.env.example

@@ -26,8 +26,8 @@ REDIS_PORT=6379
 MAIL_DRIVER=smtp
 MAIL_HOST=smtp.mailtrap.io
 MAIL_PORT=2525
-MAIL_USERNAME=null
-MAIL_PASSWORD=null
+MAIL_USERNAME=d88d6fc004652c
+MAIL_PASSWORD=aa997006998217
 MAIL_ENCRYPTION=null
 
 PUSHER_APP_ID=

README.md

@@ -7,6 +7,14 @@
 * `./dev artisan key:generate`
 * `./dev artisan migrate`
 
+## API documentation
+
+We are using [Swagger 2](https://swagger.io/) for documenting all the endpoints. The swagger file is served to the consumers
+via [readme.io](https://dash.readme.io/go/eurides-mobility-shop-api). At the moment the file needs to be manually updated
+on Readme after it changes, there is no auto sync.
+
+You can use [editor.swagger.io](https://editor.swagger.io/) for easier editing this file.
+
 ## Docker
 
 ### Installation

docs/api-endpoints.yml

@@ -4,10 +4,119 @@ info:
   version: "1.0.0"
   title: "Eurides API"
 host: "develop.eurides.mwlhq.com"
-basePath: "/"
+basePath: "/api"
 schemes:
 - "http"
 paths:
+  /signin:
+    post:
+      tags:
+      - "Authentication"
+      summary: "Request a passwordless login code via email"
+      description: ""
+      produces:
+      - "application/json"
+      parameters:
+      - in: "body"
+        name: "body"
+        description: "Email of the user that needs a login code"
+        required: true
+        schema:
+          type: object
+          properties:
+            email:
+              type: "string"
+              example: "john@doe.com"
+      responses:
+        200:
+          description: "Email was sent"
+        422:
+          description: ""
+          schema:
+            $ref: "#/definitions/ErrorResponse"
+  /signin/code:
+    post:
+      tags:
+      - "Authentication"
+      summary: "Get an access token in exchange for a passwordless login code"
+      description: ""
+      produces:
+      - "application/json"
+      parameters:
+      - in: "body"
+        name: "body"
+        description: "Passwordless login code received via email"
+        required: true
+        schema:
+          type: object
+          properties:
+            code:
+              type: "string"
+              example: "1234abcd"
+      responses:
+        200:
+          description: ""
+          schema:
+            type: object
+            properties:
+              accessToken:
+                type: "string"
+                example: "abcdefghijklmnopqrstuvwxyz"
+        422:
+          description: ""
+          schema:
+            $ref: "#/definitions/ErrorResponse"
+  /oauth/token:
+    post:
+      tags:
+      - "Authentication"
+      summary: "Get an access token using oAuth2 client_credentials grant"
+      description: ""
+      produces:
+      - "application/json"
+      parameters:
+      - in: "body"
+        name: "body"
+        description: "Client credentials of the organisation"
+        required: true
+        schema:
+          type: object
+          properties:
+            grant_type:
+              type: "string"
+              example: "client_credentials"
+            client_id:
+              type: "string"
+              example: "1233"
+            client_secret:
+              type: "string"
+              example: "abcd1234"
+      responses:
+        200:
+          description: ""
+          schema:
+            type: object
+            properties:
+              token_type:
+                type: "string"
+                example: "Bearer"
+              expires_in:
+                type: "number"
+                example: 604799
+              access_token:
+                type: "string"
+                example: "abcdefghijklmnopqrstuvwxyz"
+        401:
+          description: ""
+          schema:
+            type: object
+            properties:
+              error:
+                type: "string"
+                example: "Invalid client"
+              message:
+                type: "string"
+                example: "Client authentication failed"
   /users/me:
     get:
       tags:
@@ -1431,6 +1540,20 @@ definitions:
           page:
             type: "integer"
             example: 2
+  ErrorResponse:
+    type: "object"
+    properties:
+      message:
+        type: "string"
+        example: "The given data is invalid"
+      errors:
+        type: "array"
+        items:
+          type: "object"
+          properties:
+              email:
+                type: "string"
+                example: "The selected email is invalid."
   Subscription:
     type: "object"
     required:

routes/web.php

@@ -12,5 +12,7 @@
 */
 
 Route::get('/', function () {
-    return view('welcome');
+    return new \Illuminate\Http\JsonResponse(
+        ['message' => "Nothing to see here, move along"]
+    );
 });