From 6af55ce61d82c85e03e5a3d1a5a42e32ad09560f Mon Sep 17 00:00:00 2001 From: Hubert Van De Walle Date: Sun, 19 Apr 2020 18:42:49 +0200 Subject: [PATCH] Api doc draft --- Makefile | 10 + api-doc/api.apib | 8 + api-doc/notes/index.apib | 110 +++++++ api-doc/tags/index.apib | 14 + api-doc/users/index.apib | 48 +++ api/src/controllers/UserController.kt | 16 +- docs/index.html | 430 ++++++++++++++++++++++++++ 7 files changed, 628 insertions(+), 8 deletions(-) create mode 100644 Makefile create mode 100644 api-doc/api.apib create mode 100644 api-doc/notes/index.apib create mode 100644 api-doc/tags/index.apib create mode 100644 api-doc/users/index.apib create mode 100644 docs/index.html diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..c92d891 --- /dev/null +++ b/Makefile @@ -0,0 +1,10 @@ +api_doc_output=docs/index.html +api_blueprint_src=api-doc/api.apib +aglio_template=default +aglio_theme=cyborg + +# API doc +gen-api-doc: + aglio -i $(api_blueprint_src) -o $(api_doc_output)\ + --theme-template=$(aglio_template) \ + --theme-variables=$(aglio_theme) diff --git a/api-doc/api.apib b/api-doc/api.apib new file mode 100644 index 0000000..5913fe7 --- /dev/null +++ b/api-doc/api.apib @@ -0,0 +1,8 @@ +FORMAT: 1A +HOST: http://localhost:5000 + +# Notes API + + + + \ No newline at end of file diff --git a/api-doc/notes/index.apib b/api-doc/notes/index.apib new file mode 100644 index 0000000..4e39663 --- /dev/null +++ b/api-doc/notes/index.apib @@ -0,0 +1,110 @@ +# Data Structures + +## Chapter (object) ++ title: Chapter 1 (string) ++ content: ... (string) + + +# Group Notes + +## Notes [/notes] + +### Create a Note [POST] + ++ Request (application/json) + + Headers + Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c + + + Attributes (object) + + title: Kotlin (string) + + tags: Dev, Server (array[string]) + ++ Response 200 + +### Get Notes [GET] + ++ Request (application/json) + + Headers + Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c + + ++ Response 200 (application/json) + + Attributes (array) + + (object) + + title: Kotlin (string) + + tags: Dev, Server (array[string]) + + updatedAt: `2020-01-20T00:00:00` (string) + + (object) + + title: Java (string) + + tags: Dev (array[string]) + + updatedAt: `2018-01-20T00:00:00` (string) + + +## Note [/notes/{noteTitle}] + ++ Parameters + + noteTitle: `Kotlin` (string) - The title of the Note. + +### Get Note [GET] + ++ Request (application/json) + + Headers + Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c + ++ Response 200 (application/json) + + Attributes (object) + + title: Kotlin (string) + + tags: Dev, Server (array[string]) + + chapters (array) + + (Chapter) + + title: Introduction + + content: ... + + (Chapter) + + title: Objects + + content: ... + ++ Response 404 + +### Delete Note [DELETE] + ++ Request (application/json) + + Headers + Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c + ++ Response 204 + ++ Response 404 + +### Update a Note [PATCH] + ++ Request (application/json) + + Headers + Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c + + + Attributes (object) + + title: NewTitle (string) + + ++ Request (application/json) + + Headers + Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c + + + Attributes (object) + + tags: new, tags (array[string]) + ++ Request (application/json) + + Headers + Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c + + + Attributes (object) + + chapters (array) + + (Chapter) + + title: Introduction + + content: ... + + (Chapter) + + title: Objects + + content: ... + ++ Response 200 + ++ Response 404 \ No newline at end of file diff --git a/api-doc/tags/index.apib b/api-doc/tags/index.apib new file mode 100644 index 0000000..f8e74fe --- /dev/null +++ b/api-doc/tags/index.apib @@ -0,0 +1,14 @@ +# Group Tags + +## Tags [/tags] + +### Get all tags [GET] + ++ Request (application/json) + + Headers + Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c + + ++ Response 200 (application/json) + + Attributes + + tags: Dev, Server (array[string]) diff --git a/api-doc/users/index.apib b/api-doc/users/index.apib new file mode 100644 index 0000000..0a2237c --- /dev/null +++ b/api-doc/users/index.apib @@ -0,0 +1,48 @@ +# Data Structures + +## Login (object) ++ username: babar (string) ++ password: tortue (string) + +## Token (object) ++ token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c (string) + +## InvalidCredentials (object) ++ description: Invalid credentials (string), ++ error: Bad Request (string), ++ status_code: 401 (number) + +# Group Accounts + +## Create an account [/register] + +### Register a new user [POST] + ++ Request (application/json) + + Attributes (object) + + username: babar (string) + + email: michel@seed-it.eu (string) + + password: tortue (string) + ++ Response 200 (application/json) + + Attributes (object) + + message: Created (string) + ++ Response 409 (application/json) + + Attributes (object) + + message: User already exists (string) + + +## Authenticate user [/login] +Authenticate one user to access protected routes. + +### Authenticate a user [POST] + ++ Request (application/json) + + Attributes (Login) + ++ Response 200 (application/json) + + Attributes (Token) + ++ Response 401 (application/json) + + Attributes (InvalidCredentials) \ No newline at end of file diff --git a/api/src/controllers/UserController.kt b/api/src/controllers/UserController.kt index 304181f..05560c5 100644 --- a/api/src/controllers/UserController.kt +++ b/api/src/controllers/UserController.kt @@ -26,7 +26,7 @@ class UserController(kodein: Kodein) : KodeinController(kodein) { private val db by instance() override fun Routing.registerRoutes() { - post { + post { data class Response(val token: String) val credential = call.receive() @@ -46,10 +46,10 @@ class UserController(kodein: Kodein) : KodeinController(kodein) { return@post call.respond(Response(simpleJwt.sign(email))) } - post { + post { data class Response(val message: String) - val user = call.receive() + val user = call.receive() val exists = db.from(Users) .select() @@ -76,13 +76,13 @@ class UserController(kodein: Kodein) : KodeinController(kodein) { } object Routes { - @Location("/signin") - class SignIn + @Location("/login") + class Login - @Location("/signup") - class SignUp + @Location("/register") + class Register } } -data class SignUpInfo(val username: String, val email: String, val password: String) \ No newline at end of file +data class RegisterInfo(val username: String, val email: String, val password: String) \ No newline at end of file diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..a981db6 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,430 @@ +Notes API Back to top

Notes API

Accounts

Create an account

Register a new user
POST/register

Example URI

POST http://localhost:5000/register
Request
HideShow
Headers
Content-Type: application/json
Body
{
+  "username": "babar",
+  "email": "michel@seed",
+  "password": "tortue"
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "username": {
+      "type": "string"
+    },
+    "email": {
+      "type": "string",
+      "description": "it.eu (string)"
+    },
+    "password": {
+      "type": "string"
+    }
+  }
+}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
+  "message": "Created"
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "message": {
+      "type": "string"
+    }
+  }
+}
Response  409
HideShow
Headers
Content-Type: application/json
Body
{
+  "message": "User already exists"
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "message": {
+      "type": "string"
+    }
+  }
+}

Authenticate user

Authenticate one user to access protected routes.

+

Authenticate a user
POST/login

Example URI

POST http://localhost:5000/login
Request
HideShow
Headers
Content-Type: application/json
Body
{
+  "username": "babar",
+  "password": "tortue"
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "username": {
+      "type": "string"
+    },
+    "password": {
+      "type": "string"
+    }
+  }
+}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
+  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "token": {
+      "type": "string"
+    }
+  }
+}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
+  "description": "Invalid credentials",
+  "error": "Bad Request",
+  "status_code": 401
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "description": {
+      "type": "string"
+    },
+    "error": {
+      "type": "string"
+    },
+    "status_code": {
+      "type": "number"
+    }
+  }
+}

Notes

Notes

Create a Note
POST/notes

Example URI

POST http://localhost:5000/notes
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Body
{
+  "title": "Kotlin",
+  "tags": [
+    "Dev",
+    "Server"
+  ]
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "title": {
+      "type": "string"
+    },
+    "tags": {
+      "type": "array"
+    }
+  }
+}
Response  200

Get Notes
GET/notes

Example URI

GET http://localhost:5000/notes
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
+  {
+    "title": "Kotlin",
+    "tags": [
+      "Dev",
+      "Server"
+    ],
+    "updatedAt": "2020-01-20T00:00:00"
+  },
+  {
+    "title": "Java",
+    "tags": [
+      "Dev"
+    ],
+    "updatedAt": "2018-01-20T00:00:00"
+  }
+]
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "array"
+}

Note

Get Note
GET/notes/{noteTitle}

Example URI

GET http://localhost:5000/notes/Kotlin
URI Parameters
HideShow
noteTitle
string (required) Example: Kotlin

The title of the Note.

+
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
+  "title": "Kotlin",
+  "tags": [
+    "Dev",
+    "Server"
+  ],
+  "chapters": [
+    {
+      "title": "Introduction",
+      "content": "..."
+    },
+    {
+      "title": "Objects",
+      "content": "..."
+    }
+  ]
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "title": {
+      "type": "string"
+    },
+    "tags": {
+      "type": "array"
+    },
+    "chapters": {
+      "type": "array"
+    }
+  }
+}
Response  404

Delete Note
DELETE/notes/{noteTitle}

Example URI

DELETE http://localhost:5000/notes/Kotlin
URI Parameters
HideShow
noteTitle
string (required) Example: Kotlin

The title of the Note.

+
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Response  204
Response  404

Update a Note
PATCH/notes/{noteTitle}

Example URI

PATCH http://localhost:5000/notes/Kotlin
URI Parameters
HideShow
noteTitle
string (required) Example: Kotlin

The title of the Note.

+
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Body
{
+  "title": "NewTitle"
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "title": {
+      "type": "string"
+    }
+  }
+}
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Body
{
+  "tags": [
+    "new",
+    "tags"
+  ]
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "tags": {
+      "type": "array"
+    }
+  }
+}
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Body
{
+  "chapters": [
+    {
+      "title": "Introduction",
+      "content": "..."
+    },
+    {
+      "title": "Objects",
+      "content": "..."
+    }
+  ]
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "chapters": {
+      "type": "array"
+    }
+  }
+}
Response  200
Response  404

Tags

Tags

Get all tags
GET/tags

Example URI

GET http://localhost:5000/tags
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
+  "tags": [
+    "Dev",
+    "Server"
+  ]
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "tags": {
+      "type": "array"
+    }
+  }
+}

Generated by aglio on 19 Apr 2020

\ No newline at end of file