mirror of
https://github.com/hedgedoc/hedgedoc.git
synced 2024-11-27 12:08:02 -05:00
762 lines
23 KiB
YAML
762 lines
23 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: HedgeDoc
|
|
description: HedgeDoc is an open source collaborative note editor. Several tasks of HedgeDoc can be automated through this API.
|
|
version: 2.0.0
|
|
contact:
|
|
name: HedgeDoc on GitHub
|
|
url: https://github.com/codimd/server
|
|
license:
|
|
name: AGPLv3
|
|
url: https://github.com/codimd/server/blob/master/LICENSE
|
|
externalDocs:
|
|
description: The CodiMD Documentation.
|
|
url: https://github.com/codimd/server/tree/master/docs
|
|
servers:
|
|
- url: "/api/v2"
|
|
description: The base API Path.
|
|
security:
|
|
- bearerAuth: []
|
|
paths:
|
|
/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':
|
|
"$ref": "#/components/responses/UnauthorizedError"
|
|
/me/history:
|
|
get:
|
|
tags:
|
|
- history
|
|
- user
|
|
summary: Returns a list of the last viewed notes
|
|
operationId: getHistory
|
|
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:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/History"
|
|
'401':
|
|
"$ref": "#/components/responses/UnauthorizedError"
|
|
/me/history/{note}:
|
|
get:
|
|
tags:
|
|
- history
|
|
- user
|
|
summary: Returns History data for a note
|
|
operationId: getHistoryObject
|
|
description: JSON Object which contains id, title, tags, last visit time and pinned status
|
|
responses:
|
|
'200':
|
|
description: The list of recently viewed notes and pinned notes.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/HistoryObject"
|
|
'401':
|
|
"$ref": "#/components/responses/UnauthorizedError"
|
|
'404':
|
|
"$ref": "#/components/responses/NotFoundError"
|
|
parameters:
|
|
- name: note
|
|
in: path
|
|
required: true
|
|
description: The name of the note which is used to address it.
|
|
content:
|
|
text/plain:
|
|
example: my-note
|
|
put:
|
|
tags:
|
|
- history
|
|
- user
|
|
summary: Update the history object of the note (e.g change it's pin status)
|
|
operationId: updateHistoryObject
|
|
requestBody:
|
|
description: The updated history object.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/HistoryObject"
|
|
responses:
|
|
'200':
|
|
description: The new history.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/HistoryObject"
|
|
'401':
|
|
"$ref": "#/components/responses/UnauthorizedError"
|
|
'404':
|
|
"$ref": "#/components/responses/NotFoundError"
|
|
parameters:
|
|
- name: note
|
|
in: path
|
|
required: true
|
|
description: The note for which the revision should be shown.
|
|
content:
|
|
text/plain:
|
|
example: my-note
|
|
delete:
|
|
tags:
|
|
- history
|
|
- user
|
|
summary: Remove the note from the currently logged-in user's history
|
|
operationId: deleteHistoryObject
|
|
responses:
|
|
'204':
|
|
"$ref": "#/components/responses/SuccessfullyDeleted"
|
|
'401':
|
|
"$ref": "#/components/responses/UnauthorizedError"
|
|
'404':
|
|
"$ref": "#/components/responses/NotFoundError"
|
|
parameters:
|
|
- name: note
|
|
in: path
|
|
required: true
|
|
description: The note for which the revision should be shown.
|
|
content:
|
|
text/plain:
|
|
example: my-note
|
|
/me/notes:
|
|
get:
|
|
tags:
|
|
- user
|
|
summary: Returns a list of the notes metadata the user owns
|
|
operationId: getOwnNotes
|
|
description: The list is returned as a JSON object with an array containing each notes metadata.
|
|
responses:
|
|
'200':
|
|
description: The list of notes owned by the currently logged in user.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
description: The array that contains notes metadata.
|
|
items:
|
|
"$ref": "#/components/schemas/NoteMetadata"
|
|
'401':
|
|
"$ref": "#/components/responses/UnauthorizedError"
|
|
/notes:
|
|
post:
|
|
tags:
|
|
- 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.
|
|
security:
|
|
- bearerAuth: []
|
|
- {}
|
|
requestBody:
|
|
required: false
|
|
description: The content of the note to be imported as markdown.
|
|
content:
|
|
'text/markdown':
|
|
schema:
|
|
type: string
|
|
examples:
|
|
markdownExample:
|
|
"$ref": '#/components/examples/markdownExample'
|
|
responses:
|
|
'200':
|
|
description: Get information about the newly created note.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/Note"
|
|
'401':
|
|
"$ref": "#/components/responses/UnauthorizedError"
|
|
'403':
|
|
"$ref": "#/components/responses/ForbiddenError"
|
|
/notes/{note}:
|
|
get:
|
|
tags:
|
|
- note
|
|
summary: Returns the note
|
|
operationId: getNote
|
|
description: This includes all metadata and the content of the note.
|
|
responses:
|
|
'200':
|
|
description: All data of the note.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/Note"
|
|
'401':
|
|
"$ref": "#/components/responses/UnauthorizedError"
|
|
'403':
|
|
"$ref": "#/components/responses/ForbiddenError"
|
|
'404':
|
|
"$ref": "#/components/responses/NotFoundError"
|
|
parameters:
|
|
- name: note
|
|
in: path
|
|
required: true
|
|
description: The name of the note which is used to address it.
|
|
content:
|
|
text/plain:
|
|
example: my-note
|
|
post:
|
|
tags:
|
|
- note
|
|
summary: Imports some markdown data into a new note with a given alias
|
|
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:
|
|
required: true
|
|
description: The content of the note to be imported as markdown.
|
|
content:
|
|
'text/markdown':
|
|
schema:
|
|
type: string
|
|
examples:
|
|
markdownExample:
|
|
"$ref": '#/components/examples/markdownExample'
|
|
responses:
|
|
'200':
|
|
description: Get information about the newly created note.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/Note"
|
|
'401':
|
|
"$ref": "#/components/responses/UnauthorizedError"
|
|
'403':
|
|
"$ref": "#/components/responses/ForbiddenError"
|
|
'409':
|
|
description: This alias is already in use.
|
|
parameters:
|
|
- name: note
|
|
in: path
|
|
required: true
|
|
description: The name of the note which is used to address it.
|
|
content:
|
|
text/plain:
|
|
example: my-note
|
|
delete:
|
|
tags:
|
|
- note
|
|
summary: Remove the note
|
|
operationId: deleteNote
|
|
responses:
|
|
'204':
|
|
"$ref": "#/components/responses/SuccessfullyDeleted"
|
|
'401':
|
|
"$ref": "#/components/responses/UnauthorizedError"
|
|
'403':
|
|
"$ref": "#/components/responses/ForbiddenError"
|
|
'404':
|
|
"$ref": "#/components/responses/NotFoundError"
|
|
parameters:
|
|
- name: note
|
|
in: path
|
|
required: true
|
|
description: The note for which the revision should be shown.
|
|
content:
|
|
text/plain:
|
|
example: my-note
|
|
put:
|
|
tags:
|
|
- note
|
|
summary: Imports some markdown data into an existing note, creating a new revision
|
|
operationId: createNewRevisionForNote
|
|
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:
|
|
required: true
|
|
description: The content of the note to be imported as markdown.
|
|
content:
|
|
'text/markdown':
|
|
schema:
|
|
type: string
|
|
examples:
|
|
markdownExample:
|
|
"$ref": '#/components/examples/markdownExample'
|
|
responses:
|
|
'200':
|
|
description: The new, changed note
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/Note"
|
|
'401':
|
|
"$ref": "#/components/responses/UnauthorizedError"
|
|
'403':
|
|
"$ref": "#/components/responses/ForbiddenError"
|
|
'404':
|
|
"$ref": "#/components/responses/NotFoundError"
|
|
parameters:
|
|
- name: note
|
|
in: path
|
|
required: true
|
|
description: The note for which the info should be shown.
|
|
content:
|
|
text/plain:
|
|
example: my-note
|
|
/notes/{note}/metadata:
|
|
put:
|
|
tags:
|
|
- note
|
|
summary: Set the permissions of a note
|
|
operationId: updateNoteMetadata
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/NoteMetadata"
|
|
responses:
|
|
'200':
|
|
description: The updated permissions of the note.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/NoteMetadata"
|
|
'401':
|
|
"$ref": "#/components/responses/UnauthorizedError"
|
|
'403':
|
|
"$ref": "#/components/responses/ForbiddenError"
|
|
'404':
|
|
"$ref": "#/components/responses/NotFoundError"
|
|
parameters:
|
|
- name: note
|
|
in: path
|
|
required: true
|
|
description: The note for which the info should be shown.
|
|
content:
|
|
text/plain:
|
|
example: my-note
|
|
get:
|
|
tags:
|
|
- note
|
|
summary: Get the permissions of a note
|
|
operationId: getNoteMetadata
|
|
responses:
|
|
'200':
|
|
description: The permissions of the note.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/NoteMetadata"
|
|
'401':
|
|
"$ref": "#/components/responses/UnauthorizedError"
|
|
'403':
|
|
"$ref": "#/components/responses/ForbiddenError"
|
|
'404':
|
|
"$ref": "#/components/responses/NotFoundError"
|
|
parameters:
|
|
- name: note
|
|
in: path
|
|
required: true
|
|
description: The note for which the info should be shown.
|
|
content:
|
|
text/plain:
|
|
example: my-note
|
|
/notes/{note}/revisions:
|
|
get:
|
|
tags:
|
|
- note
|
|
summary: Returns a list of the available note revisions
|
|
operationId: getAllRevisionsOfNote
|
|
description: The list contains the revision-id, the length and a ISO-timestamp of the creation date.
|
|
responses:
|
|
'200':
|
|
description: Revisions of the note.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/NoteRevisionsMetadata"
|
|
'401':
|
|
"$ref": "#/components/responses/UnauthorizedError"
|
|
'403':
|
|
"$ref": "#/components/responses/ForbiddenError"
|
|
'404':
|
|
"$ref": "#/components/responses/NotFoundError"
|
|
parameters:
|
|
- name: note
|
|
in: path
|
|
required: true
|
|
description: The note for which revisions should be shown.
|
|
content:
|
|
text/plain:
|
|
example: my-note
|
|
/notes/{note}/revisions/{revision-id}:
|
|
get:
|
|
tags:
|
|
- note
|
|
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.
|
|
responses:
|
|
'200':
|
|
description: Revision of the note for the given id.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/NoteRevision"
|
|
'401':
|
|
"$ref": "#/components/responses/UnauthorizedError"
|
|
'403':
|
|
"$ref": "#/components/responses/ForbiddenError"
|
|
'404':
|
|
"$ref": "#/components/responses/NotFoundError"
|
|
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 of the revision to fetch.
|
|
content:
|
|
text/plain:
|
|
example: 1570921051959
|
|
/notes/{note}/content:
|
|
get:
|
|
tags:
|
|
- note
|
|
- export
|
|
summary: Returns the raw markdown content of a note
|
|
operationId: getNoteContent
|
|
responses:
|
|
'200':
|
|
description: The raw markdown content of the note.
|
|
content:
|
|
'text/markdown':
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
'401':
|
|
"$ref": "#/components/responses/UnauthorizedError"
|
|
'403':
|
|
"$ref": "#/components/responses/ForbiddenError"
|
|
'404':
|
|
"$ref": "#/components/responses/NotFoundError"
|
|
parameters:
|
|
- name: note
|
|
in: path
|
|
required: true
|
|
description: The note for which the markdown should be exported.
|
|
content:
|
|
text/plain:
|
|
example: my-note
|
|
/media/upload:
|
|
post:
|
|
tags:
|
|
- media
|
|
summary: Uploads an image to the backend storage
|
|
description: Uploads an image to be processed by the backend.
|
|
requestBody:
|
|
required: true
|
|
description: The binary image to upload.
|
|
content:
|
|
image/*:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
responses:
|
|
'200':
|
|
description: The image was uploaded successfully.
|
|
'401':
|
|
"$ref": "#/components/responses/UnauthorizedError"
|
|
'403':
|
|
"$ref": "#/components/responses/ForbiddenError"
|
|
/monitoring:
|
|
get:
|
|
tags:
|
|
- monitoring
|
|
summary: Returns the current status of the backend
|
|
operationId: getMonitoring
|
|
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"
|
|
'401':
|
|
"$ref": "#/components/responses/UnauthorizedError"
|
|
'403':
|
|
"$ref": "#/components/responses/ForbiddenError"
|
|
/monitoring/prometheus:
|
|
get:
|
|
tags:
|
|
- monitoring
|
|
summary: Returns the current status of the backend for Prometheus.
|
|
operationId: getPrometheus
|
|
description: The data is returned in Prometheus Exposition Format
|
|
responses:
|
|
'200':
|
|
description: Prometheus compatible monitoring data.
|
|
content:
|
|
text/plain: {}
|
|
'401':
|
|
"$ref": "#/components/responses/UnauthorizedError"
|
|
'403':
|
|
"$ref": "#/components/responses/ForbiddenError"
|
|
components:
|
|
schemas:
|
|
UserInfo:
|
|
type: object
|
|
properties:
|
|
userName:
|
|
type: string
|
|
displayName:
|
|
type: string
|
|
photo:
|
|
type: string
|
|
format: uri
|
|
email:
|
|
type: string
|
|
format: email
|
|
UserPasswordChange:
|
|
type: object
|
|
properties:
|
|
password:
|
|
type: string
|
|
ImageProxyRequest:
|
|
type: object
|
|
properties:
|
|
src:
|
|
type: string
|
|
description: The url of the image that should be processed by the image proxy.
|
|
ImageProxyResponse:
|
|
type: object
|
|
properties:
|
|
src:
|
|
type: string
|
|
description: The url of the provied version of the image.
|
|
Note:
|
|
type: object
|
|
properties:
|
|
content:
|
|
type: string
|
|
description: The markdown content of the note
|
|
metadata:
|
|
$ref: "#/components/schemas/NoteMetadata"
|
|
editedByAtPosition:
|
|
type: array
|
|
description: Data which gives insights about who worked where on the note.
|
|
items:
|
|
type: integer
|
|
description: Unique user ids and additional data
|
|
NoteMetadata:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: UUIDv4
|
|
description: The id of the note.
|
|
alias:
|
|
type: string
|
|
description: The alias of the note.
|
|
title:
|
|
type: string
|
|
description: Title of the note
|
|
description:
|
|
type: string
|
|
description: Description of the note.
|
|
tags:
|
|
type: array
|
|
description: A list of tags attached to the note.
|
|
items:
|
|
type: string
|
|
description: A tag
|
|
updateTime:
|
|
type: string
|
|
description: ISO-timestamp of when the note was last changed.
|
|
updateUser:
|
|
$ref: "#/components/schemas/UserInfo"
|
|
viewCount:
|
|
type: integer
|
|
minimum: 0
|
|
description: How often the published version of the note was viewed.
|
|
createTime:
|
|
type: string
|
|
description: The ISO-timestamp when the note was created in ISO 8601 format.
|
|
editedBy:
|
|
type: array
|
|
description: List of usernames who edited the note.
|
|
items:
|
|
type: string
|
|
permissions:
|
|
$ref: "#/components/schemas/NotePermissions"
|
|
NotePermissions:
|
|
type: object
|
|
properties:
|
|
owner:
|
|
type: string
|
|
description: Username of the owner of the note
|
|
sharedTo:
|
|
type: array
|
|
description: Contains all usernames that can read the note and a boolean that denotes if they can also edit.
|
|
items:
|
|
type: object
|
|
properties:
|
|
username:
|
|
type: string
|
|
canEdit:
|
|
type: boolean
|
|
|
|
NoteRevisionsMetadata:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: The id of the revision
|
|
createdTime:
|
|
type: string
|
|
description: ISO-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.
|
|
NoteRevision:
|
|
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
|
|
GistLink:
|
|
type: object
|
|
properties:
|
|
link:
|
|
type: string
|
|
format: uri
|
|
description: A Gist link.
|
|
DropboxLink:
|
|
type: object
|
|
properties:
|
|
link:
|
|
type: string
|
|
format: uri
|
|
description: A Dropbox link.
|
|
EmailLogin:
|
|
type: object
|
|
properties:
|
|
email:
|
|
type: string
|
|
format: email
|
|
password:
|
|
type: string
|
|
format: password
|
|
LdapLogin:
|
|
type: object
|
|
properties:
|
|
username:
|
|
type: string
|
|
format: email
|
|
password:
|
|
type: string
|
|
format: password
|
|
OpenIdLogin:
|
|
type: object
|
|
properties:
|
|
openId:
|
|
type: string
|
|
ServerStatus:
|
|
type: object
|
|
properties:
|
|
serverVersion:
|
|
type: object
|
|
properties:
|
|
major:
|
|
type: integer
|
|
minor:
|
|
type: integer
|
|
patch:
|
|
type: integer
|
|
preRelease:
|
|
type: string
|
|
commit:
|
|
type: string
|
|
description: Version of the server specified according to SemVer specification
|
|
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
|
|
HistoryObject:
|
|
type: object
|
|
properties:
|
|
metadata:
|
|
$ref: "#/components/schemas/NoteMetadata"
|
|
pinned:
|
|
type: boolean
|
|
description: Whether the user has pinned this note.
|
|
History:
|
|
type: object
|
|
properties:
|
|
history:
|
|
type: array
|
|
description: The array that contains history objects.
|
|
items:
|
|
"$ref": "#/components/schemas/HistoryObject"
|
|
examples:
|
|
markdownExample:
|
|
value: '# Some header\nSome normal text. **Some bold text**'
|
|
summary: A sample markdown content
|
|
securitySchemes:
|
|
bearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
responses:
|
|
UnauthorizedError:
|
|
description: Authorization information is missing or invalid.
|
|
ForbiddenError:
|
|
description: Access to the requested resource is not permitted.
|
|
NotFoundError:
|
|
description: The requested resource was not found.
|
|
SuccessfullyDeleted:
|
|
description: The requested resource was sucessfully deleted.
|