mirror of
https://github.com/hedgedoc/hedgedoc.git
synced 2025-05-12 22:26:08 -04:00
540 lines
16 KiB
YAML
540 lines
16 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: CodiMD
|
|
description: CodiMD is an open source collaborative note editor. Several tasks of CodiMD can be automated through this API.
|
|
version: 2.0.0
|
|
contact:
|
|
name: CodiMD on GitHub
|
|
url: https://github.com/codimd/server
|
|
license:
|
|
name: AGPLv3
|
|
url: https://github.com/codimd/server/blob/master/LICENSE
|
|
externalDocs:
|
|
description: CodiMD Documentation
|
|
url: https://github.com/codimd/server/tree/master/docs
|
|
servers:
|
|
- url: "/api/v2.0/"
|
|
description: "Base API Path"
|
|
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
|
|
headers:
|
|
Set-Cookie:
|
|
schema:
|
|
type: string
|
|
/auth/ldap:
|
|
post:
|
|
tags:
|
|
- auth
|
|
summary: Trying to login via LDAP
|
|
operationId: loginLdap
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/LdapLogin'
|
|
responses:
|
|
200:
|
|
description: login succesful
|
|
headers:
|
|
Set-Cookie:
|
|
schema:
|
|
type: string
|
|
/auth/openid:
|
|
post:
|
|
tags:
|
|
- auth
|
|
summary: Trying to login via OpenID
|
|
operationId: loginOpenId
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/OpenIdLogin'
|
|
responses:
|
|
200:
|
|
description: login succesful
|
|
headers:
|
|
Set-Cookie:
|
|
schema:
|
|
type: string
|
|
/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"
|
|
/note:
|
|
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.
|
|
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/NewNote"
|
|
/note/{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"
|
|
404:
|
|
description: Note does not exist
|
|
parameters:
|
|
- name: note
|
|
in: path
|
|
required: true
|
|
description: The note for which the info should be shown
|
|
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/NewNote"
|
|
409:
|
|
description: This alias is already in use
|
|
parameters:
|
|
- name: note
|
|
in: path
|
|
required: true
|
|
description: The note for which the info should be shown
|
|
content:
|
|
text/plain:
|
|
example: my-note
|
|
/note/{note}/export/markdown:
|
|
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
|
|
404:
|
|
description: Note does not exist
|
|
parameters:
|
|
- name: note
|
|
in: path
|
|
required: true
|
|
description: The note for which the markdown should be exported
|
|
content:
|
|
text/plain:
|
|
example: my-note
|
|
/note/{note}/export/html:
|
|
get:
|
|
tags:
|
|
- note
|
|
- export
|
|
summary: Returns the content of a note as HTML.
|
|
operationId: getNoteContentAsHTML
|
|
responses:
|
|
200:
|
|
description: The raw html content of the note
|
|
content:
|
|
'text/html':
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
404:
|
|
description: Note does not exist
|
|
parameters:
|
|
- name: note
|
|
in: path
|
|
required: true
|
|
description: The note for which the html should be exported
|
|
content:
|
|
text/plain:
|
|
example: my-note
|
|
/note/{note}/export/gist:
|
|
get:
|
|
tags:
|
|
- note
|
|
- export
|
|
summary: Exports the content of a note to a gist.
|
|
operationId: exportNoteToGist
|
|
responses:
|
|
200:
|
|
description: The link to Gist of the note
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": '#/components/schemas/GistLink'
|
|
404:
|
|
description: Note does not exist
|
|
parameters:
|
|
- name: note
|
|
in: path
|
|
required: true
|
|
description: The note which should be exported to gist
|
|
content:
|
|
text/plain:
|
|
example: my-note
|
|
/note/{note}/export/dropbox:
|
|
get:
|
|
tags:
|
|
- note
|
|
- export
|
|
summary: Exports the content of a note to dropbox.
|
|
operationId: exportNoteToDropbox
|
|
responses:
|
|
200:
|
|
description: The dropbox link of the note
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": '#/components/schemas/DropboxLink'
|
|
404:
|
|
description: Note does not exist
|
|
parameters:
|
|
- name: note
|
|
in: path
|
|
required: true
|
|
description: The note which should be exported to dropbox
|
|
content:
|
|
text/plain:
|
|
example: my-note
|
|
/note/{note}/export/pdf:
|
|
get:
|
|
tags:
|
|
- note
|
|
- export
|
|
summary: Exports the content of a note as PDF.
|
|
operationId: exportNoteToPDF
|
|
responses:
|
|
200:
|
|
description: The note as an PDF
|
|
content:
|
|
application/pdf:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
404:
|
|
description: Note does not exist
|
|
parameters:
|
|
- name: note
|
|
in: path
|
|
required: true
|
|
description: The note which should be exported to dropbox
|
|
content:
|
|
text/plain:
|
|
example: my-note
|
|
/note/{note}/revision:
|
|
get:
|
|
tags:
|
|
- note
|
|
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.
|
|
responses:
|
|
200:
|
|
description: Revisions of the note
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/NoteRevisionsMetadata"
|
|
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/{note}/revision/{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 timestamp
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/NoteRevision"
|
|
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
|
|
components:
|
|
schemas:
|
|
UserInfo:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: UUIDv4
|
|
name:
|
|
type: string
|
|
photo:
|
|
type: string
|
|
format: uri
|
|
Note:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: UUIDv4
|
|
description: The id of the note
|
|
alias:
|
|
type: string
|
|
description: The alias of the note
|
|
lastChange:
|
|
type: object
|
|
properties:
|
|
userId:
|
|
type: string
|
|
format: UUIDv4
|
|
description: The id of the user that last changed the note
|
|
user:
|
|
type: string
|
|
description: The name of the user that last changed the note
|
|
timestamp:
|
|
type: integer
|
|
description: UNIX-timestamp of when the note was last changed.
|
|
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.
|
|
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
|
|
NoteRevisionsMetadata:
|
|
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
|
|
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
|
|
NewNote:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: the id of the new note
|
|
format: UUIDv4
|
|
alias:
|
|
type: string
|
|
description: the alias with which the note should be accessed
|
|
ServerStatus:
|
|
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
|
|
examples:
|
|
markdownExample:
|
|
value: '# Some header\nSome normal text. **Some bold text**'
|
|
summary: A sample markdown content
|