mirrors/hedgedoc
1
0
Fork 0
mirror of https://github.com/hedgedoc/hedgedoc.git synced 2025-05-24 20:14:35 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Rename openapi.yml to public_api.yml

Browse source
This commit is contained in:
David Mehren 2020-07-21 20:40:49 +02:00
parent f1dddb8a41
commit ee3837c7e5
No known key found for this signature in database
GPG key ID: 185982BA4C42B7C3
1 changed files with 0 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

834
docs/dev/public_api.yml Normal file
View file

@ -0,0 +1,834 @@
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}:
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/SuccesfullyDeleted"
'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 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/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 note for which the info should be shown.
content:
text/plain:
example: my-note
delete:
tags:
- note
summary: Remove the note
operationId: deleteNote
responses:
'204':
"$ref": "#/components/responses/SuccesfullyDeleted"
'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 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"
'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 timestamp.
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 (timestamp) 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
format: UUIDv4
displayName:
type: string
photo:
type: string
format: uri
email:
type: string
format: email
UserPasswordChange:
type: object
properties:
password:
type: string
UserUpdate:
type: object
properties:
name:
type: string
description: The new display name of the user.
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.
Config:
type: object
properties:
allowAnonymous:
type: boolean
description: Whether anonymous notes are allowed.
authProviders:
type: object
properties:
facebook:
type: boolean
description: Whether Facebook login is possible.
github:
type: boolean
description: Whether GitHub login is possible.
twitter:
type: boolean
description: Whether Twitter login is possible.
gitlab:
type: boolean
description: Whether Gitlab login is possible.
dropbox:
type: boolean
description: Whether Dropbox login is possible.
google:
type: boolean
description: Whether Google login is possible.
saml:
type: boolean
description: Whether SAML login is possible.
oauth2:
type: boolean
description: Whether OAuth2 login is possible.
email:
type: boolean
description: Whether E-Mail login is possible.
ldap:
type: boolean
description: Whether LDAP login is possible.
openid:
type: boolean
description: Whether OpenID login is possible.
customAuthNames:
type: object
properties:
ldap:
type: string
description: The custom name for the LDAP Login.
example: "FooBar LDAP"
oauth2:
type: string
description: The custom name for the OAuth2 Login.
example: "Olaf2"
saml:
type: string
description: The custom name for the SAML Login.
example: "aufSAMLn.de"
specialLinks:
type: object
properties:
privacy:
type: string
format: uri
description: Link to the privacy notice.
termsOfUse:
type: string
format: uri
description: Link to the terms of use.
imprint:
type: string
format: uri
description: Link to the imprint.
version:
type: object
properties:
version:
type: string
sourceCodeUrl:
type: string
format: uri
issueTrackerUrl:
type: string
format: uri
Note:
type: object
properties:
content:
type: string
description: The markdown content of the note
metadata:
type: object
$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: object
properties:
username:
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.
editedBy:
type: array
description: List of usernames who edited the note.
items:
type: string
permissions:
type: object
$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: 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
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:
type: object
$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.
SuccesfullyDeleted:
description: The requested resource was sucessfully deleted.