github/hedgedoc
1
0
Fork 0
mirror of https://github.com/hedgedoc/hedgedoc.git synced 2024-11-24 18:56:32 -05:00
Code Issues Projects Releases Packages Wiki Activity

added openapi definition for api 2.0

Browse source
This commit is contained in:
Philip Molares 2020-05-24 21:00:16 +02:00 committed by David Mehren
parent 2654f1fa36
commit 4e2f7d9db5
No known key found for this signature in database
GPG key ID: 185982BA4C42B7C3
1 changed files with 237 additions and 326 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

563
docs/dev/openapi.yml
View file

@ -1,164 +1,186 @@
openapi: 3.0.1 openapi: 3.0.3
info: info:
title: CodiMD title: CodiMD
description: CodiMD is an open source collaborative note editor. Several tasks of CodiMD can be automated through this API. description: CodiMD is an open source collaborative note editor. Several tasks of CodiMD can be automated through this API.
version: 1.6.0 version: 2.0.0
contact: contact:
name: CodiMD on GitHub name: CodiMD on GitHub
url: https://github.com/codimd/server url: https://github.com/codimd/server
license: license:
name: AGPLv3 name: AGPLv3
url: https://github.com/codimd/server/blob/master/LICENSE url: https://github.com/codimd/server/blob/master/LICENSE
externalDocs: externalDocs:
url: https://github.com/codimd/server/blob/master/docs/dev/api.md description: CodiMD Documentation
url: https://github.com/codimd/server/tree/master/docs
servers:
- url: "/api/v2.0/"
description: "Base API Path"
paths: paths:
/auth/email:
post:
tags:
- auth
summary: Trying to login via email
operationId: loginEmail
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EmailLogin'
responses:
200:
description: login succesful
content: {}
/me:
get:
tags:
- user
summary: Get the user information of the currently logged in user
operationId: getMe
responses:
200:
description: the user information
content:
application/json:
schema:
"$ref": "#/components/schemas/UserInfo"
401:
description: the user is not logged in
content: {}
/me/export:
get:
tags:
- user
summary: Exports a zip-archive with all notes of the current user.
responses:
200:
description: The zip-archive with all notes
/status:
get:
tags:
- server
summary: Returns the current status of the CodiMD instance.
operationId: getStatus
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:
application/json:
schema:
"$ref": "#/components/schemas/ServerStatus"
/new: /new:
get: get:
tags: tags:
- note - note
summary: Creates a new note. summary: Creates a new note.
operationId: createNote
description: A random id will be assigned and the content will equal to the template (blank by default). After note creation a redirect is issued to the created note. description: A random id will be assigned and the content will equal to the template (blank by default). After note creation a redirect is issued to the created note.
responses: responses:
default: 200:
description: Redirect to the new note description: Get information about the newly created note
content:
application/json:
schema:
"$ref": "#/components/schemas/NewNote"
post: post:
tags: tags:
- note - note
summary: Imports some markdown data into a new note. summary: Imports some markdown data into a new note.
operationId: createNoteFromMarkdown
description: A random id will be assigned and the content will equal to the body of the received HTTP-request. description: A random id will be assigned and the content will equal to the body of the received HTTP-request.
requestBody: requestBody:
required: true required: true
description: The content of the note to be imported as markdown description: The content of the note to be imported as markdown
content: content:
'text/markdown': 'text/markdown':
example: '# Some header' schema:
type: string
examples:
markdownExample:
"$ref": '#/components/examples/markdownExample'
responses: responses:
default: 200:
description: Redirect to the imported note description: Get information about the newly created note
content:
application/json:
schema:
"$ref": "#/components/schemas/NewNote"
/new/{alias}: /new/{alias}:
post: post:
tags: tags:
- note - note
summary: Imports some markdown data into a new note with a given alias. summary: Imports some markdown data into a new note with a given alias.
description: 'This endpoint equals to the above one except that the alias from the url will be assigned to the note if [FreeURL-mode](../configuration-env-vars.md#users-and-privileges) is enabled.' operationId: createNoteWithAlias
description: 'This endpoint equals to the above one except that the alias from the url will be assigned to the note if [FreeURL-mode](https://github.com/codimd/server/tree/master/docs/configuration-env-vars.md#users-and-privileges) is enabled.'
requestBody: requestBody:
required: true required: true
description: The content of the note to be imported as markdown description: The content of the note to be imported as markdown
content: content:
'text/markdown': 'text/markdown':
example: '# Some heading' schema:
type: string
examples:
markdownExample:
"$ref": '#/components/examples/markdownExample'
responses: responses:
default: 200:
description: Redirect to the imported note description: Get information about the newly created note
content:
application/json:
schema:
"$ref": "#/components/schemas/NewNote"
409:
description: This alias is already in use
parameters: parameters:
- - name: alias
name: alias
in: path in: path
required: true required: true
description: The alias for the note-id under which the note will be saved description: The alias for the note-id under which the note will be saved
content: content:
'text/plain': text/plain:
example: my-note example: my-note
/{note}/download: /{note}/download:
get: get:
tags: tags:
- note - note
summary: Returns the raw markdown content of a note. summary: Returns the raw markdown content of a note.
operationId: getNoteContent
responses: responses:
200: 200:
description: The raw markdown content of the note description: The raw markdown content of the note
content: content:
'text/markdown': 'text/markdown':
example: '# Some heading' schema:
type: string
examples:
markdownExample:
"$ref": '#/components/examples/markdownExample'
404: 404:
description: Note does not exist description: Note does not exist
parameters: parameters:
- - name: note
name: note
in: path in: path
required: true required: true
description: The note which should be downloaded description: The note which should be downloaded
content: content:
'text/plain': text/plain:
example: my-note example: my-note
/{note}/publish:
get:
tags:
- note
summary: Redirects to the published version of the note.
responses:
default:
description: Redirect to the published version of the note
404:
description: Note does not exist
parameters:
- name: note
in: path
required: true
description: The note which should be published
content:
'text/plain':
example: my-note
/{note}/slide:
get:
tags:
- note
summary: Redirects to the slide-presentation of the note.
description: This is only useful on notes which are designed to be slides.
responses:
default:
description: Redirect to the slide version of the note
404:
description: Note does not exist
parameters:
- name: note
in: path
required: true
description: The note which should be shown as slide
content:
'text/plain':
example: my-note
/{note}/info: /{note}/info:
get: get:
tags: tags:
- note - note
summary: Returns metadata about the note. summary: Returns metadata about the note.
operationId: getNoteInfo
description: This includes the title and description of the note as well as the creation date and viewcount. description: This includes the title and description of the note as well as the creation date and viewcount.
responses: responses:
200: 200:
description: Metadata about the note description: Metadata about the note
content: content:
'text/json': application/json:
schema: schema:
type: object "$ref": "#/components/schemas/NoteInfo"
properties:
title:
type: string
description: The title of the note
default: Untitled
description:
type: string
description: The description of the note or the first words from the note
viewcount:
type: integer
minimum: 0
description: How often the published version of the note was viewed
createtime:
type: string
description: The timestamp when the note was created in ISO 8601 format.
updatetime:
type: string
description: The timestamp when the note was last updated in ISO 8601 format.
404: 404:
description: Note does not exist description: Note does not exist
parameters: parameters:
@ -167,35 +189,22 @@ paths:
required: true required: true
description: The note for which the info should be shown description: The note for which the info should be shown
content: content:
'text/plain': text/plain:
example: my-note example: my-note
/{note}/revision: /{note}/revision:
get: get:
tags: tags:
- note - note
summary: Returns a list of the available note revisions. summary: Returns a list of the available note revisions.
operationId: getAllRevisionsOfNote
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. 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: responses:
200: 200:
description: Revisions of the note description: Revisions of the note
content: content:
'text/json': application/json:
schema: schema:
type: object "$ref": "#/components/schemas/NoteRevisionsMetadata"
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: 404:
description: Note does not exist description: Note does not exist
parameters: parameters:
@ -204,7 +213,7 @@ paths:
required: true required: true
description: The note for which revisions should be shown description: The note for which revisions should be shown
content: content:
'text/plain': text/plain:
example: my-note example: my-note
/{note}/revision/{revision-id}: /{note}/revision/{revision-id}:
@ -212,29 +221,15 @@ paths:
tags: tags:
- note - note
summary: Returns the revision of the note with some metadata. summary: Returns the revision of the note with some metadata.
operationId: getSpecificRevisionOfNote
description: The revision is returned as a JSON object with the content of the note and the authorship. description: The revision is returned as a JSON object with the content of the note and the authorship.
responses: responses:
200: 200:
description: Revision of the note for the given timestamp description: Revision of the note for the given timestamp
content: content:
'text/json': application/json:
schema: schema:
type: object "$ref": "#/components/schemas/NoteRevision"
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: 404:
description: Note does not exist description: Note does not exist
parameters: parameters:
@ -243,216 +238,132 @@ paths:
required: true required: true
description: The note for which the revision should be shown description: The note for which the revision should be shown
content: content:
'text/plain': text/plain:
example: my-note example: my-note
- name: revision-id - name: revision-id
in: path in: path
required: true required: true
description: The id (timestamp) of the revision to fetch description: The id (timestamp) of the revision to fetch
content: content:
'text/plain': text/plain:
example: 1570921051959 example: 1570921051959
components:
/{note}/gist: schemas:
get: UserInfo:
tags: type: object
- note properties:
summary: Creates a new GitHub Gist with the note's content. id:
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.' type: string
responses: format: UUIDv4
default: name:
description: Redirect to the created gist (or the GitHub authentication before) type: string
404: photo:
description: Note does not exist type: string
parameters: format: uri
- name: note NoteRevisionsMetadata:
in: path type: object
required: true properties:
description: The note which should be pasted to GitHub gist revision:
content: type: array
'text/plain': description: Array that holds all revision-info objects
example: my-note items:
type: object
/me: properties:
get: time:
tags: type: integer
- user description: UNIX-timestamp of when the revision was saved. Is also the revision-id.
summary: Returns the profile data of the current logged-in user. length:
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. type: integer
responses: description: Length of the document to the timepoint the revision was saved
200: NoteRevision:
description: If the user is logged-in, the user data otherwise `{"status":"forbidden"}` type: object
content: properties:
'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: content:
'application/x-www-form-urlencoded': type: string
example: 'history=[{"id":"example","text":"Untitled","time":1556275442010,"tags":[],"pinned":false}]' description: The raw markdown content of the note revision
responses: authorship:
200: type: array
description: History replaced description: Data which gives insights about who worked on the note
delete: items:
tags: type: integer
- user description: Unique user ids and additional data
summary: Deletes the user's history. patch:
responses: type: array
200: description: Data which gives insight about what changed in comparison to former revisions
description: User's history deleted items:
type: string
/history/{note}: NoteInfo:
post: type: object
tags: properties:
- user title:
summary: Toggles the pinned status in the history for a note. type: string
description: The body must be form-encoded and contain a field `pinned` that is either `true` or `false`. description: The title of the note
requestBody: default: Untitled
required: true description:
content: type: string
'application/x-www-form-urlencoded': description: The description of the note or the first words from the note
example: 'pinned=false' viewcount:
responses: type: integer
200: minimum: 0
description: Pinned state toggled description: How often the published version of the note was viewed
parameters: createtime:
- name: note type: string
in: path description: The timestamp when the note was created in ISO 8601 format.
required: true updatetime:
description: The note for which the pinned state should be toggled type: string
content: description: The timestamp when the note was last updated in ISO 8601 format.
'text/plain': EmailLogin:
example: my-note type: object
delete: properties:
tags: email:
- user type: string
summary: Deletes a note from the user's history. format: email
responses: password:
200: type: string
description: Pinned state toggled format: password
parameters: NewNote:
- name: note type: object
in: path properties:
required: true id:
description: The note for which the pinned state should be toggled type: string
content: description: the id of the new note
'text/plain': format: UUIDv4
example: my-note alias:
type: string
/status: description: the alias with which the note should be accessed
get: ServerStatus:
tags: type: object
- server properties:
summary: Returns the current status of the CodiMD instance. onlineNotes:
description: The data is returned as a JSON object containing the number of notes stored on the server, (distinct) online users and more. type: integer
responses: description: How many notes are edited at the moment
200: onlineUsers:
description: The server info type: integer
content: description: How many users are online at the moment
'text/json': distinctOnlineUsers:
schema: type: integer
type: object description: How many distinct users (different machines) are online at the moment
properties: notesCount:
onlineNotes: type: integer
type: integer description: How many notes are stored on the server
description: How many notes are edited at the moment registeredUsers:
onlineUsers: type: integer
type: integer description: How many users are registered on the server
description: How many users are online at the moment onlineRegisteredUsers:
distinctOnlineUsers: type: integer
type: integer description: How many of the online users are registered on the server
description: How many distinct users (different machines) are online at the moment distinctOnlineRegisteredUsers:
notesCount: type: integer
type: integer description: How many of the distinct online users are registered on the server
description: How many notes are stored on the server isConnectionBusy:
registeredUsers: type: boolean
type: integer connectionSocketQueueLength:
description: How many users are registered on the server type: integer
onlineRegisteredUsers: isDisconnectBusy:
type: integer type: boolean
description: How many of the online users are registered on the server disconnectSocketQueueLength:
distinctOnlineRegisteredUsers: type: integer
type: integer examples:
description: How many of the distinct online users are registered on the server markdownExample:
isConnectionBusy: value: '# Some header\nSome normal text. **Some bold text**'
type: boolean summary: A sample markdown content
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.