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:
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:
type: object
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.
"$ref": "#/components/schemas/NoteInfo"
404:
description: Note does not exist
parameters:
@ -167,35 +189,22 @@ paths:
required: true
description: The note for which the info should be shown
content:
'text/plain':
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:
'text/json':
application/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
"$ref": "#/components/schemas/NoteRevisionsMetadata"
404:
description: Note does not exist
parameters:
@ -204,7 +213,7 @@ paths:
required: true
description: The note for which revisions should be shown
content:
'text/plain':
text/plain:
example: my-note
/{note}/revision/{revision-id}:
@ -212,29 +221,15 @@ paths:
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:
'text/json':
application/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
"$ref": "#/components/schemas/NoteRevision"
404:
description: Note does not exist
parameters:
@ -243,216 +238,132 @@ paths:
required: true
description: The note for which the revision should be shown
content:
'text/plain':
text/plain:
example: my-note
- name: revision-id
in: path
required: true
description: The id (timestamp) of the revision to fetch
content:
'text/plain':
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
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:
'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.
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:
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.
EmailLogin:
type: object
properties:
email:
type: string
format: email
password:
type: string
format: password
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