mirror of
https://github.com/hedgedoc/hedgedoc.git
synced 2024-11-23 02:06:29 -05:00
added openapi definition for api 2.0
This commit is contained in:
Philip Molares
David Mehren
parent
8689b44f59
commit
c7511df450
1 changed files with 237 additions and 326 deletions
|
|
@ -1,145 +1,298 @@
|
|||
openapi: 3.0.1
|
||||
|
||||
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: 1.6.0
|
||||
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:
|
||||
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:
|
||||
|
||||
/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:
|
||||
get:
|
||||
tags:
|
||||
- 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.
|
||||
responses:
|
||||
default:
|
||||
description: Redirect to the new note
|
||||
200:
|
||||
description: Get information about the newly created note
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
"$ref": "#/components/schemas/NewNote"
|
||||
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: true
|
||||
description: The content of the note to be imported as markdown
|
||||
content:
|
||||
'text/markdown':
|
||||
example: '# Some header'
|
||||
schema:
|
||||
type: string
|
||||
examples:
|
||||
markdownExample:
|
||||
"$ref": '#/components/examples/markdownExample'
|
||||
responses:
|
||||
default:
|
||||
description: Redirect to the imported note
|
||||
|
||||
200:
|
||||
description: Get information about the newly created note
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
"$ref": "#/components/schemas/NewNote"
|
||||
/new/{alias}:
|
||||
post:
|
||||
tags:
|
||||
- note
|
||||
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:
|
||||
required: true
|
||||
description: The content of the note to be imported as markdown
|
||||
content:
|
||||
'text/markdown':
|
||||
example: '# Some heading'
|
||||
schema:
|
||||
type: string
|
||||
examples:
|
||||
markdownExample:
|
||||
"$ref": '#/components/examples/markdownExample'
|
||||
responses:
|
||||
default:
|
||||
description: Redirect to the imported note
|
||||
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: alias
|
||||
- name: alias
|
||||
in: path
|
||||
required: true
|
||||
description: The alias for the note-id under which the note will be saved
|
||||
content:
|
||||
'text/plain':
|
||||
text/plain:
|
||||
example: my-note
|
||||
|
||||
/{note}/download:
|
||||
get:
|
||||
tags:
|
||||
- note
|
||||
summary: Returns the raw markdown content of a note.
|
||||
operationId: getNoteContent
|
||||
responses:
|
||||
200:
|
||||
description: The raw markdown content of the note
|
||||
content:
|
||||
'text/markdown':
|
||||
example: '# Some heading'
|
||||
schema:
|
||||
type: string
|
||||
examples:
|
||||
markdownExample:
|
||||
"$ref": '#/components/examples/markdownExample'
|
||||
404:
|
||||
description: Note does not exist
|
||||
parameters:
|
||||
-
|
||||
name: note
|
||||
- name: note
|
||||
in: path
|
||||
required: true
|
||||
description: The note which should be downloaded
|
||||
content:
|
||||
'text/plain':
|
||||
text/plain:
|
||||
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:
|
||||
get:
|
||||
tags:
|
||||
- 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.
|
||||
responses:
|
||||
200:
|
||||
description: Metadata about the note
|
||||
content:
|
||||
'text/json':
|
||||
application/json:
|
||||
schema:
|
||||
"$ref": "#/components/schemas/NoteInfo"
|
||||
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
|
||||
/{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}/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
|
||||
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
|
||||
NoteInfo:
|
||||
type: object
|
||||
properties:
|
||||
title:
|
||||
|
|
@ -159,264 +312,26 @@ paths:
|
|||
updatetime:
|
||||
type: string
|
||||
description: The timestamp when the note was last updated in ISO 8601 format.
|
||||
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
|
||||
|
||||
/{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:
|
||||
EmailLogin:
|
||||
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:
|
||||
email:
|
||||
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:
|
||||
format: email
|
||||
password:
|
||||
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:
|
||||
format: password
|
||||
NewNote:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: The id or alias of the note
|
||||
text:
|
||||
description: the id of the new note
|
||||
format: UUIDv4
|
||||
alias:
|
||||
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:
|
||||
description: the alias with which the note should be accessed
|
||||
ServerStatus:
|
||||
type: object
|
||||
properties:
|
||||
onlineNotes:
|
||||
|
|
@ -448,11 +363,7 @@ paths:
|
|||
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.
|
||||
examples:
|
||||
markdownExample:
|
||||
value: '# Some header\nSome normal text. **Some bold text**'
|
||||
summary: A sample markdown content
|
||||
|
|
|
|||
Loading…
Reference in a new issue