summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorErik Michelson2019-10-17 23:26:48 +0200
committerErik Michelson2019-10-17 23:26:48 +0200
commitb7c02a901fcea5519a94762ac081e2124172188c (patch)
tree89d8ff2778303d905512c99adcd2e945d6fb3dec
parent93ca037a759ea34c40ef069a78d29505d0ac300d (diff)
Finishing openapi doc
version 1.6.0 is noted as this document already contains the 1.6.0 endpoint /new/alias Signed-off-by: Erik Michelson <erik@liltv.de>
Diffstat (limited to '')
-rw-r--r--docs/dev/openapi.yml289
1 files changed, 288 insertions, 1 deletions
diff --git a/docs/dev/openapi.yml b/docs/dev/openapi.yml
index d53c9f09..b2a896fa 100644
--- a/docs/dev/openapi.yml
+++ b/docs/dev/openapi.yml
@@ -188,7 +188,294 @@ paths:
- name: note
in: path
required: true
- description: The note which should be published
+ description: The note for which the info should be shown
content:
'text/plain':
example: my-note
+
+ /{note}/revision:
+ get:
+ tags:
+ - note
+ summary: Returns a list of the available note revisions.
+ description: The list is returned as a JSON object with an array of revision-id and length associations. The revision-id equals to the timestamp when the revision was saved.
+ responses:
+ 200:
+ description: Revisions of the note
+ content:
+ 'text/json':
+ schema:
+ type: object
+ properties:
+ revision:
+ type: array
+ description: Array that holds all revision-info objects
+ items:
+ type: object
+ properties:
+ time:
+ type: integer
+ description: UNIX-timestamp of when the revision was saved. Is also the revision-id.
+ length:
+ type: integer
+ description: Length of the document to the timepoint the revision was saved
+ 404:
+ description: Note does not exist
+ parameters:
+ - name: note
+ in: path
+ required: true
+ description: The note for which revisions should be shown
+ content:
+ 'text/plain':
+ example: my-note
+
+ /{note}/revision/{revision-id}:
+ get:
+ tags:
+ - note
+ summary: Returns the revision of the note with some metadata.
+ description: The revision is returned as a JSON object with the content of the note and the authorship.
+ responses:
+ 200:
+ description: Revision of the note for the given timestamp
+ content:
+ 'text/json':
+ schema:
+ type: object
+ properties:
+ content:
+ type: string
+ description: The raw markdown content of the note revision
+ authorship:
+ type: array
+ description: Data which gives insights about who worked on the note
+ items:
+ type: integer
+ description: Unique user ids and additional data
+ patch:
+ type: array
+ description: Data which gives insight about what changed in comparison to former revisions
+ items:
+ type: string
+ 404:
+ description: Note does not exist
+ parameters:
+ - name: note
+ in: path
+ required: true
+ description: The note for which the revision should be shown
+ content:
+ 'text/plain':
+ example: my-note
+ - name: revision-id
+ in: path
+ required: true
+ description: The id (timestamp) of the revision to fetch
+ content:
+ 'text/plain':
+ example: 1570921051959
+
+ /{note}/gist:
+ get:
+ tags:
+ - note
+ summary: Creates a new GitHub Gist with the note's content.
+ description: 'If [GitHub integration](https://github.com/codimd/server/blob/master/docs/configuration-env-vars.md#github-login) is configured, the user will be redirected to GitHub and a new Gist with the content of the note will be created.'
+ responses:
+ default:
+ description: Redirect to the created gist (or the GitHub authentication before)
+ 404:
+ description: Note does not exist
+ parameters:
+ - name: note
+ in: path
+ required: true
+ description: The note which should be pasted to GitHub gist
+ content:
+ 'text/plain':
+ example: my-note
+
+ /me:
+ get:
+ tags:
+ - user
+ summary: Returns the profile data of the current logged-in user.
+ description: The data is returned as a JSON object containing the user-id, the user's name and a url to the profile picture. Requires an active session of the user.
+ responses:
+ 200:
+ description: If the user is logged-in, the user data otherwise `{"status":"forbidden"}`
+ content:
+ 'text/json':
+ schema:
+ type: object
+ properties:
+ status:
+ type: string
+ description: ok if everything works as expected, forbidden is the user is not logged-in
+ id:
+ type: string
+ description: Unique id of the user
+ name:
+ type: string
+ description: The user's display name
+ photo:
+ type: string
+ description: An url to the online stored user profile photo
+
+ /me/export:
+ get:
+ tags:
+ - user
+ summary: Exports a zip-archive with all notes of the current user.
+ responses:
+ default:
+ description: The zip-archive with all notes
+
+ /history:
+ get:
+ tags:
+ - user
+ summary: Returns a list of the last viewed notes.
+ description: The list is returned as a JSON object with an array containing for each entry it's id, title, tags, last visit time and pinned status.
+ responses:
+ 200:
+ description: The list of recently viewed notes and pinned notes
+ content:
+ 'text/json':
+ schema:
+ type: object
+ properties:
+ history:
+ type: array
+ description: The array that contains history objects
+ items:
+ type: object
+ properties:
+ id:
+ type: string
+ description: The id or alias of the note
+ text:
+ type: string
+ description: The title of the note
+ time:
+ type: integer
+ description: The UNIX-timestamp when the note was last accessed by the user
+ tags:
+ type: array
+ description: The tags that were added by the user to the note
+ items:
+ type: string
+ pinned:
+ type: boolean
+ description: Whether the user has pinned this note
+ post:
+ tags:
+ - user
+ summary: Replace user's history with a new one.
+ description: The body must be form-encoded and contain a field `history` with a JSON-encoded array like its returned from the server when exporting the history.
+ requestBody:
+ required: true
+ content:
+ 'application/x-www-form-urlencoded':
+ example: 'history=[{"id":"example","text":"Untitled","time":1556275442010,"tags":[],"pinned":false]'
+ responses:
+ 200:
+ description: History replaced
+ delete:
+ tags:
+ - user
+ summary: Deletes the user's history.
+ responses:
+ 200:
+ description: User's history deleted
+
+ /history/{note}:
+ post:
+ tags:
+ - user
+ summary: Toggles the pinned status in the history for a note.
+ description: The body must be form-encoded and contain a field `pinned` that is either `true` or `false`.
+ requestBody:
+ required: true
+ content:
+ 'application/x-www-form-urlencoded':
+ example: 'pinned=false'
+ responses:
+ 200:
+ description: Pinned state toggled
+ parameters:
+ - name: note
+ in: path
+ required: true
+ description: The note for which the pinned state should be toggled
+ content:
+ 'text/plain':
+ example: my-note
+ delete:
+ tags:
+ - user
+ summary: Deletes a note from the user's history.
+ responses:
+ 200:
+ description: Pinned state toggled
+ parameters:
+ - name: note
+ in: path
+ required: true
+ description: The note for which the pinned state should be toggled
+ content:
+ 'text/plain':
+ example: my-note
+
+ /status:
+ get:
+ tags:
+ - server
+ summary: Returns the current status of the CodiMD instance.
+ description: The data is returned as a JSON object containing the number of notes stored on the server, (distinct) online users and more.
+ responses:
+ 200:
+ description: The server info
+ content:
+ 'text/json':
+ schema:
+ type: object
+ properties:
+ onlineNotes:
+ type: integer
+ description: How many notes are edited at the moment
+ onlineUsers:
+ type: integer
+ description: How many users are online at the moment
+ distinctOnlineUsers:
+ type: integer
+ description: How many distinct users (different machines) are online at the moment
+ notesCount:
+ type: integer
+ description: How many notes are stored on the server
+ registeredUsers:
+ type: integer
+ description: How many users are registered on the server
+ onlineRegisteredUsers:
+ type: integer
+ description: How many of the online users are registered on the server
+ distinctOnlineRegisteredUsers:
+ type: integer
+ description: How many of the distinct online users are registered on the server
+ isConnectionBusy:
+ type: boolean
+ connectionSocketQueueLength:
+ type: integer
+ isDisconnectBusy:
+ type: boolean
+ disconnectSocketQueueLength:
+ type: integer
+
+tags:
+ - name: note
+ description: These endpoints create notes, return information about them or export them.
+ - name: user
+ description: These endpoints return information about the current logged-in user and it's note history. If no user is logged-in, the most of this requests will fail with either a HTTP 403 or a JSON object containing `{"status":"forbidden"}`.
+ - name: server
+ description: These endpoints return information about the running CodiMD instance.