From 1e685a9ea2c13f5de4fe72f04476701f2ff63bf4 Mon Sep 17 00:00:00 2001
From: eikek <eike.kettner@posteo.de>
Date: Sat, 12 Jun 2021 19:04:27 +0200
Subject: [PATCH 1/4] Update sbt openapi plugin and use redoc for documentation
---
build.sbt | 5 +++--
project/plugins.sbt | 2 +-
2 files changed, 4 insertions(+), 3 deletions(-)
diff --git a/build.sbt b/build.sbt
index 0422c9ab..013014da 100644
--- a/build.sbt
+++ b/build.sbt
@@ -412,7 +412,7 @@ val restapi = project
openapiTargetLanguage := Language.Scala,
openapiPackage := Pkg("docspell.restapi.model"),
openapiSpec := (Compile / resourceDirectory).value / "docspell-openapi.yml",
- openapiStaticArgs := Seq("-l", "html2")
+ openapiStaticGen := OpenApiDocGenerator.Redoc
)
.dependsOn(common)
@@ -431,7 +431,8 @@ val joexapi = project
Dependencies.http4sClient,
openapiTargetLanguage := Language.Scala,
openapiPackage := Pkg("docspell.joexapi.model"),
- openapiSpec := (Compile / resourceDirectory).value / "joex-openapi.yml"
+ openapiSpec := (Compile / resourceDirectory).value / "joex-openapi.yml",
+ openapiStaticGen := OpenApiDocGenerator.Redoc
)
.dependsOn(common)
diff --git a/project/plugins.sbt b/project/plugins.sbt
index 8690f525..ea1c008a 100644
--- a/project/plugins.sbt
+++ b/project/plugins.sbt
@@ -1,6 +1,6 @@
addSbtPlugin("ch.epfl.scala" % "sbt-scalafix" % "0.9.29")
addSbtPlugin("com.eed3si9n" % "sbt-buildinfo" % "0.10.0")
-addSbtPlugin("com.github.eikek" % "sbt-openapi-schema" % "0.7.1")
+addSbtPlugin("com.github.eikek" % "sbt-openapi-schema" % "0.8.0")
addSbtPlugin("com.github.sbt" % "sbt-release" % "1.0.15")
addSbtPlugin("com.github.sbt" % "sbt-pgp" % "2.1.2")
addSbtPlugin("io.kevinlee" % "sbt-github-pages" % "0.5.0")
From 8791326d6a23c74f4dde1c4d733e45b10ccb3347 Mon Sep 17 00:00:00 2001
From: eikek <eike.kettner@posteo.de>
Date: Sat, 12 Jun 2021 19:12:52 +0200
Subject: [PATCH 2/4] Fix openapi linter warnings
---
.../src/main/resources/joex-openapi.yml | 26 +-
.../src/main/resources/docspell-openapi.yml | 240 +++++++++++++++---
2 files changed, 232 insertions(+), 34 deletions(-)
diff --git a/modules/joexapi/src/main/resources/joex-openapi.yml b/modules/joexapi/src/main/resources/joex-openapi.yml
index e5d56457..8dfd9a71 100644
--- a/modules/joexapi/src/main/resources/joex-openapi.yml
+++ b/modules/joexapi/src/main/resources/joex-openapi.yml
@@ -3,6 +3,16 @@ openapi: 3.0.0
info:
title: Docspell JOEX
version: 0.24.0-SNAPSHOT
+ description: |
+ This is the remote API to the job executor component of Docspell.
+ Docspell is a free document management system focused on small
+ groups or families.
+
+ The routes are not protected by the application. This api is meant
+ to be used by the server component of Docspell.
+ license:
+ name: GPLv3
+ url: https://spdx.org/licenses/GPL-3.0-or-later.html
servers:
- url: /api/v1
@@ -11,6 +21,7 @@ servers:
paths:
/api/info/version:
get:
+ operationId: "info-version"
tags: [ Api Info ]
summary: Get basic information about this software.
description: |
@@ -22,8 +33,9 @@ paths:
application/json:
schema:
$ref: "#/components/schemas/VersionInfo"
- /api/v1/notify:
+ /notify:
post:
+ operationId: "v1-notify"
tags: [ Job Executor ]
summary: Notify the job executor.
description: |
@@ -35,8 +47,9 @@ paths:
application/json:
schema:
$ref: "#/components/schemas/BasicResult"
- /api/v1/running:
+ /running:
get:
+ operationId: "v1-running"
tags: [ Job Executor ]
summary: Get a list of currently executing jobs.
description: |
@@ -48,8 +61,9 @@ paths:
application/json:
schema:
$ref: "#/components/schemas/JobList"
- /api/v1/shutdownAndExit:
+ /shutdownAndExit:
post:
+ operationId: "v1-shutdown-and-exit"
tags: [ Job Executor ]
summary: Stops this component and exits.
description: |
@@ -61,8 +75,9 @@ paths:
application/json:
schema:
$ref: "#/components/schemas/BasicResult"
- /api/v1/job/{id}:
+ /job/{id}:
get:
+ operationId: "v1-job-by-id"
tags: [ Current Jobs ]
summary: Get a job by its id.
description: |
@@ -76,8 +91,9 @@ paths:
application/json:
schema:
$ref: "#/components/schemas/JobAndLog"
- /api/v1/job/{id}/cancel:
+ /job/{id}/cancel:
post:
+ operationId: "v1-job-cancel"
tags: [ Current Jobs ]
summary: Request to cancel a running job.
description: |
diff --git a/modules/restapi/src/main/resources/docspell-openapi.yml b/modules/restapi/src/main/resources/docspell-openapi.yml
index c1d28f84..cf0345f6 100644
--- a/modules/restapi/src/main/resources/docspell-openapi.yml
+++ b/modules/restapi/src/main/resources/docspell-openapi.yml
@@ -4,7 +4,24 @@ info:
title: Docspell
version: 0.24.0-SNAPSHOT
description: |
- This is the remote API to Docspell, a personal document organizer.
+ This is the remote API to Docspell. Docspell is a free document
+ management system focused on small groups or families.
+
+ The routes can be divided into protected, unprotected routes and
+ admin routes. The unprotected, or open routes are at `/open/*`
+ while the protected routes are at `/sec/*` and admin routes are at
+ `/admin/*`. Open routes don't require authenticated access and can
+ be used by any user. The protected routes require an authenticated
+ user. The admin routes require a special http header with a value
+ from the config file. They are disabled by default, you need to
+ specify a secret in order to enable admin routes.
+ license:
+ name: GPLv3
+ url: https://spdx.org/licenses/GPL-3.0-or-later.html
+
+externalDocs:
+ description: Docspell Homepage
+ url: https://docspell.org
servers:
- url: /api/v1
@@ -13,6 +30,7 @@ servers:
paths:
/api/info/version:
get:
+ operationId: "api-info-version"
tags: [ Information ]
summary: Get version information.
description: |
@@ -26,6 +44,7 @@ paths:
$ref: "#/components/schemas/VersionInfo"
/open/auth/login:
post:
+ operationId: "open-auth-login"
tags: [ Authentication ]
summary: Authenticate with account name and password.
description: |
@@ -49,6 +68,7 @@ paths:
$ref: "#/components/schemas/AuthResult"
/open/checkfile/{id}/{checksum}:
get:
+ operationId: "open-checkfile-checksum-by-id"
tags: [ Upload ]
summary: Check if a file is in docspell.
description: |
@@ -69,6 +89,7 @@ paths:
$ref: "#/components/schemas/CheckFileResult"
/open/upload/item/{id}:
post:
+ operationId: "open-upload-new-item-by-source"
tags: [ Upload ]
summary: Upload files to docspell.
description: |
@@ -111,6 +132,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/open/upload/item/{itemId}/{id}:
post:
+ operationId: "open-upload-to-item-by-source"
tags: [ Upload ]
summary: Upload files to docspell.
description: |
@@ -153,6 +175,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/admin/fts/reIndexAll:
post:
+ operationId: "admin-fts-reindex-all"
tags: [Full-Text Index, Admin]
summary: Re-creates the full-text index.
description: |
@@ -176,6 +199,7 @@ paths:
/sec/fts/reIndex:
post:
+ operationId: "sec-fts-reindex"
tags: [Full-Text Index]
summary: Re-creates the full-text index for the current collective
description: |
@@ -193,6 +217,7 @@ paths:
/sec/checkfile/{checksum}:
get:
+ operationId: "sec-checkfile-by-checksum"
tags: [ Upload ]
summary: Check if a file is in docspell.
description: |
@@ -214,6 +239,7 @@ paths:
$ref: "#/components/schemas/CheckFileResult"
/sec/upload/item:
post:
+ operationId: "sec-upload-new-item"
tags: [ Upload ]
summary: Upload files to docspell.
description: |
@@ -255,6 +281,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/upload/{itemId}:
post:
+ operationId: "sec-upload-to-item"
tags: [ Upload ]
summary: Upload files to docspell.
description: |
@@ -299,6 +326,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/open/integration/item/{id}:
get:
+ operationId: "open-integration-item-check-collective"
tags: [ Integration Endpoint ]
summary: Check if integration endpoint is available.
description: |
@@ -325,6 +353,7 @@ paths:
401:
description: Unauthorized
post:
+ operationId: "open-integration-item-upload"
tags: [ Integration Endpoint ]
summary: Upload files to docspell.
description: |
@@ -370,6 +399,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/open/integration/checkfile/{id}/{checksum}:
get:
+ operationId: "open-integration-checkfile-by-checksum"
tags: [ Integration Endpoint ]
summary: Check if a file is in docspell.
description: |
@@ -394,6 +424,7 @@ paths:
/open/signup/register:
post:
+ operationId: "open-signup-register"
tags: [ Registration ]
summary: Register a new account.
description: |
@@ -412,6 +443,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/open/signup/newinvite:
post:
+ operationId: "open-signup-newinvite"
tags: [ Registration ]
summary: Generate a new invite.
description: |
@@ -434,6 +466,7 @@ paths:
$ref: "#/components/schemas/InviteResult"
/sec/auth/session:
post:
+ operationId: "sec-auth-session"
tags: [ Authentication ]
summary: Authentication with a token
description: |
@@ -450,6 +483,7 @@ paths:
$ref: "#/components/schemas/AuthResult"
/sec/auth/logout:
post:
+ operationId: "sec-auth-logout"
tags: [ Authentication ]
summary: Logout.
description: |
@@ -463,6 +497,7 @@ paths:
/sec/tag:
get:
+ operationId: "sec-tag-get-all"
tags: [ Tags ]
summary: Get a list of tags
description: |
@@ -479,6 +514,7 @@ paths:
schema:
$ref: "#/components/schemas/TagList"
post:
+ operationId: "sec-tag-new"
tags: [ Tags ]
summary: Create a new tag.
description: |
@@ -499,6 +535,7 @@ paths:
schema:
$ref: "#/components/schemas/BasicResult"
put:
+ operationId: "sec-tag-edit"
tags: [ Tags ]
summary: Change an existing tag.
description: |
@@ -520,6 +557,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/tag/{id}:
delete:
+ operationId: "sec-tag-delete-by-id"
tags: [ Tags ]
summary: Delete a tag.
description: |
@@ -537,6 +575,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/organization:
get:
+ operationId: "sec-org-get-all"
tags: [ Organization ]
summary: Get a list of organizations.
description: |
@@ -556,6 +595,7 @@ paths:
- $ref: "#/components/schemas/ReferenceList"
- $ref: "#/components/schemas/OrganizationList"
post:
+ operationId: "sec-org-new"
tags: [ Organization ]
summary: Create a new organization.
description: |
@@ -576,6 +616,7 @@ paths:
schema:
$ref: "#/components/schemas/BasicResult"
put:
+ operationId: "sec-org-edit"
tags: [ Organization ]
summary: Change an existing organization.
description: |
@@ -597,6 +638,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/organization/{id}:
get:
+ operationId: "sec-org-details"
tags: [ Organization ]
summary: Get a list of organizations.
description: |
@@ -613,6 +655,7 @@ paths:
schema:
$ref: "#/components/schemas/Organization"
delete:
+ operationId: "sec-org-delete-by-id"
tags: [ Organization ]
summary: Delete a organization by its id.
description: |
@@ -630,6 +673,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/person:
get:
+ operationId: "sec-persion-get-all"
tags: [ Person ]
summary: Get a list of persons.
description: |
@@ -649,6 +693,7 @@ paths:
- $ref: "#/components/schemas/ReferenceList"
- $ref: "#/components/schemas/PersonList"
post:
+ operationId: "sec-person-new"
tags: [ Person ]
summary: Create a new person.
description: |
@@ -669,6 +714,7 @@ paths:
schema:
$ref: "#/components/schemas/BasicResult"
put:
+ operationId: "sec-person-edit"
tags: [ Person ]
summary: Change an existing person.
description: |
@@ -690,6 +736,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/person/{id}:
get:
+ operationId: "sec-person-details"
tags: [ Person ]
summary: Get person details.
description: |
@@ -706,6 +753,7 @@ paths:
schema:
$ref: "#/components/schemas/Person"
delete:
+ operationId: "sec-person-delete-by-id"
tags: [ Person ]
summary: Delete a person by its id.
description: |
@@ -723,6 +771,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/equipment:
get:
+ operationId: "sec-equip-get-all"
tags: [ Equipment ]
summary: Get a list of equipments
description: |
@@ -739,6 +788,7 @@ paths:
schema:
$ref: "#/components/schemas/EquipmentList"
post:
+ operationId: "sec-equip-new"
tags: [ Equipment ]
summary: Create a new equipment.
description: |
@@ -759,6 +809,7 @@ paths:
schema:
$ref: "#/components/schemas/BasicResult"
put:
+ operationId: "sec-equip-edit"
tags: [ Equipment ]
summary: Change an existing equipment.
description: |
@@ -780,6 +831,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/equipment/{id}:
get:
+ operationId: "sec-equip-details"
tags: [ Equipment ]
summary: Get details about a single equipment.
description: |
@@ -797,6 +849,7 @@ paths:
$ref: "#/components/schemas/Equipment"
delete:
+ operationId: "sec-equip-delete-by-id"
tags: [ Equipment ]
summary: Delete a equipment.
description: |
@@ -815,6 +868,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/folder:
get:
+ operationId: "sec-folder-get-all"
tags: [ Folder ]
summary: Get a list of folders.
description: |
@@ -838,6 +892,7 @@ paths:
schema:
$ref: "#/components/schemas/FolderList"
post:
+ operationId: "sec-folder-new"
tags: [ Folder ]
summary: Create a new folder
description: |
@@ -859,6 +914,7 @@ paths:
$ref: "#/components/schemas/IdResult"
/sec/folder/{id}:
get:
+ operationId: "sec-folder-details"
tags: [ Folder ]
summary: Get folder details.
description: |
@@ -875,6 +931,7 @@ paths:
schema:
$ref: "#/components/schemas/FolderDetail"
put:
+ operationId: "sec-folder-edit-name"
tags: [ Folder ]
summary: Change the name of a folder
description: |
@@ -896,6 +953,7 @@ paths:
schema:
$ref: "#/components/schemas/BasicResult"
delete:
+ operationId: "sec-folder-delete-by-id"
tags: [ Folder ]
summary: Delete a folder by its id.
description: |
@@ -913,6 +971,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/folder/{id}/member/{userId}:
put:
+ operationId: "sec-folder-add-member"
tags: [ Folder ]
summary: Add a member to this folder
description: |
@@ -930,6 +989,7 @@ paths:
schema:
$ref: "#/components/schemas/BasicResult"
delete:
+ operationId: "sec-folder-delete-member"
tags: [ Folder ]
summary: Removes a member from this folder.
description: |
@@ -949,6 +1009,7 @@ paths:
/sec/collective:
get:
+ operationId: "sec-collective-get-all"
tags: [ Collective ]
summary: Get information about your collective
description: |
@@ -964,6 +1025,7 @@ paths:
$ref: "#/components/schemas/Collective"
/sec/collective/settings:
get:
+ operationId: "sec-collective-get-settings"
tags: [ Collective ]
summary: Get collective settings
description: |
@@ -978,6 +1040,7 @@ paths:
schema:
$ref: "#/components/schemas/CollectiveSettings"
post:
+ operationId: "sec-collective-update-settings"
tags: [ Collective ]
summary: Update settings for a collective
description: |
@@ -998,6 +1061,7 @@ paths:
$ref: "#/components/schemas/Collective"
/sec/collective/insights:
get:
+ operationId: "sec-collective-get-insights"
tags: [ Collective ]
summary: Get some insights regarding your items.
description: |
@@ -1014,6 +1078,7 @@ paths:
$ref: "#/components/schemas/ItemInsights"
/sec/collective/tagcloud:
get:
+ operationId: "sec-collective-tag-cloud"
tags: [ Collective ]
summary: Summary of used tags.
description: |
@@ -1030,6 +1095,7 @@ paths:
/sec/collective/contacts:
get:
+ operationId: "sec-collective-contacts-get-all"
tags: [ Collective ]
summary: Return a list of contacts.
description: |
@@ -1050,6 +1116,7 @@ paths:
/sec/collective/classifier/startonce:
post:
+ operationId: "sec-collective-classifier-start-now"
tags: [ Collective ]
summary: Starts the learn-classifier task
description: |
@@ -1071,6 +1138,7 @@ paths:
/sec/collective/previews:
post:
+ operationId: "sec-collective-previews-start-generate"
tags: [ Collective ]
summary: Starts the generate previews task
description: |
@@ -1094,6 +1162,7 @@ paths:
/sec/user:
get:
+ operationId: "sec-user-get-all"
tags: [ Collective ]
summary: Get a list of collective users.
description: |
@@ -1108,6 +1177,7 @@ paths:
schema:
$ref: "#/components/schemas/UserList"
post:
+ operationId: "sec-user-new"
tags: [ Collective ]
summary: Create a new collective user.
description: |
@@ -1128,6 +1198,7 @@ paths:
schema:
$ref: "#/components/schemas/BasicResult"
put:
+ operationId: "sec-user-edit"
tags: [ Collective ]
summary: Change an existing user.
description: |
@@ -1149,6 +1220,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/user/{id}:
delete:
+ operationId: "sec-user-delete-by-id"
tags: [ Collective ]
summary: Delete a user.
description: |
@@ -1166,6 +1238,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/user/changePassword:
post:
+ operationId: "sec-user-change-password"
tags: [ Collective ]
summary: Change the password.
description: |
@@ -1189,6 +1262,7 @@ paths:
parameters:
- $ref: "#/components/parameters/clientId"
get:
+ operationId: "sec-clientsettings-get"
tags: [ Client Settings ]
summary: Return the current user settings
description: |
@@ -1205,6 +1279,7 @@ paths:
application/json:
schema: {}
put:
+ operationId: "sec-clientsettings-update"
tags: [ Client Settings ]
summary: Update current user settings
description: |
@@ -1232,6 +1307,7 @@ paths:
schema:
$ref: "#/components/schemas/BasicResult"
delete:
+ operationId: "sec-clientsettings-delete"
tags: [ Client Settings ]
summary: Clears the current user settings
description: |
@@ -1249,6 +1325,7 @@ paths:
/admin/user/resetPassword:
post:
+ operationId: "admin-user-reset-password"
tags: [ Collective, Admin ]
summary: Reset a user password.
description: |
@@ -1273,6 +1350,7 @@ paths:
/sec/source:
get:
+ operationId: "sec-source-get-all"
tags: [ Source ]
summary: Get a list of sources
description: |
@@ -1287,6 +1365,7 @@ paths:
schema:
$ref: "#/components/schemas/SourceList"
post:
+ operationId: "sec-source-new"
tags: [ Source ]
summary: Create a new source.
description: |
@@ -1307,6 +1386,7 @@ paths:
schema:
$ref: "#/components/schemas/BasicResult"
put:
+ operationId: "sec-source-edit"
tags: [ Source ]
summary: Change an existing source.
description: |
@@ -1328,6 +1408,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/source/{id}:
delete:
+ operationId: "sec-source-delete-by-id"
tags: [ Source ]
summary: Delete a source.
description: |
@@ -1347,6 +1428,7 @@ paths:
/sec/item/convertallpdfs:
post:
+ operationId: "sec-item-convert-all-pdfs"
tags: [ Item ]
summary: Convert all non-converted pdfs.
description: |
@@ -1373,6 +1455,7 @@ paths:
/sec/item/search:
get:
+ operationId: "sec-item-search-by-get"
tags: [ Item Search ]
summary: Search for items.
description: |
@@ -1397,6 +1480,7 @@ paths:
schema:
$ref: "#/components/schemas/ItemLightList"
post:
+ operationId: "sec-item-search-by-post"
tags: [ Item Search ]
summary: Search for items.
description: |
@@ -1423,6 +1507,7 @@ paths:
/sec/item/searchIndex:
post:
+ operationId: "sec-item-search-index"
tags: [ Item Search ]
summary: Search for items using full-text search only.
description: |
@@ -1454,6 +1539,7 @@ paths:
/sec/item/searchStats:
post:
+ operationId: "sec-item-search-stats-get"
tags: [ Item Search ]
summary: Get basic statistics about search results.
description: |
@@ -1474,6 +1560,7 @@ paths:
schema:
$ref: "#/components/schemas/SearchStats"
get:
+ operationId: "sec-item-search-stats-post"
tags: [ Item Search ]
summary: Get basic statistics about search results.
description: |
@@ -1493,6 +1580,7 @@ paths:
/sec/item/{id}:
get:
+ operationId: "sec-item-details"
tags: [ Item ]
summary: Get details about an item.
description: |
@@ -1509,6 +1597,7 @@ paths:
schema:
$ref: "#/components/schemas/ItemDetail"
delete:
+ operationId: "sec-item-delete-by-id"
tags: [ Item ]
summary: Delete an item.
description: |
@@ -1526,6 +1615,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/item/{id}/tags:
put:
+ operationId: "sec-item-get-tags"
tags: [ Item ]
summary: Set new set of tags.
description: |
@@ -1549,6 +1639,7 @@ paths:
schema:
$ref: "#/components/schemas/BasicResult"
post:
+ operationId: "sec-item-create-and-add-tag"
tags: [ Item ]
summary: Add a new tag to an item.
description: |
@@ -1576,6 +1667,7 @@ paths:
/sec/item/{id}/taglink:
post:
+ operationId: "sec-item-link-tags"
tags: [Item]
summary: Link existing tags to an item.
description: |
@@ -1601,6 +1693,7 @@ paths:
/sec/item/{id}/tagtoggle:
post:
+ operationId: "sec-item-toggle-tags"
tags: [Item]
summary: Toggles existing tags to an item.
description: |
@@ -1628,6 +1721,7 @@ paths:
/sec/item/{id}/direction:
put:
+ operationId: "sec-item-set-direction"
tags: [ Item ]
summary: Set the direction of an item.
description: |
@@ -1650,6 +1744,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/item/{id}/folder:
put:
+ operationId: "sec-item-set-folder"
tags: [ Item ]
summary: Set a folder for this item.
description: |
@@ -1675,6 +1770,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/item/{id}/corrOrg:
put:
+ operationId: "sec-item-set-org"
tags: [ Item ]
summary: Set the correspondent organization of an item.
description: |
@@ -1696,6 +1792,7 @@ paths:
schema:
$ref: "#/components/schemas/BasicResult"
post:
+ operationId: "sec-item-create-and-set-org"
tags: [ Item ]
summary: Set a new correspondent organization of an item.
description: |
@@ -1719,6 +1816,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/item/{id}/corrPerson:
put:
+ operationId: "sec-item-set-corr-person"
tags: [ Item ]
summary: Set the correspondent person of an item.
description: |
@@ -1740,6 +1838,7 @@ paths:
schema:
$ref: "#/components/schemas/BasicResult"
post:
+ operationId: "sec-item-create-and-set-corr-person"
tags: [ Item ]
summary: Create and set the correspondent person of an item.
description: |
@@ -1763,6 +1862,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/item/{id}/concPerson:
put:
+ operationId: "sec-item-set-conc-person"
tags: [ Item ]
summary: Set the concerning person of an item.
description: |
@@ -1784,6 +1884,7 @@ paths:
schema:
$ref: "#/components/schemas/BasicResult"
post:
+ operationId: "sec-item-create-and-set-conc-person"
tags: [ Item ]
summary: Create and set the concerning person of an item.
description: |
@@ -1807,6 +1908,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/item/{id}/concEquipment:
put:
+ operationId: "sec-item-set-equip"
tags: [ Item ]
summary: Set the concering equipment of an item.
description: |
@@ -1828,6 +1930,7 @@ paths:
schema:
$ref: "#/components/schemas/BasicResult"
post:
+ operationId: "sec-item-create-and-set-equip"
tags: [ Item ]
summary: Create and set a new the concering equipment of an item.
description: |
@@ -1851,6 +1954,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/item/{id}/notes:
put:
+ operationId: "sec-item-set-notes"
tags: [ Item ]
summary: Set notes of an item.
description: |
@@ -1873,6 +1977,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/item/{id}/name:
put:
+ operationId: "sec-item-set-name"
tags: [ Item ]
summary: Set the name of an item.
description: |
@@ -1895,6 +2000,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/item/{id}/confirm:
post:
+ operationId: "sec-item-confirm"
tags: [ Item ]
summary: Confirms the current meta data of an item.
description: |
@@ -1913,6 +2019,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/item/{id}/unconfirm:
post:
+ operationId: "sec-item-unconfirm"
tags: [ Item ]
summary: Puts an item back to created state.
description: |
@@ -1931,6 +2038,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/item/{id}/date:
put:
+ operationId: "sec-item-set-date"
tags: [ Item ]
summary: Sets the item date.
description: |
@@ -1953,6 +2061,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/item/{id}/duedate:
put:
+ operationId: "sec-item-set-duedate"
tags: [ Item ]
summary: Sets the items due date.
description: |
@@ -1975,6 +2084,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/item/{id}/proposals:
get:
+ operationId: "sec-item-get-proposals"
tags: [ Item ]
summary: Get a list of proposals for this item.
description: |
@@ -1994,13 +2104,13 @@ paths:
$ref: "#/components/schemas/ItemProposals"
/sec/item/{id}/preview:
head:
+ operationId: "sec-item-check-preview"
tags: [ Attachment ]
summary: Get a preview image of an attachment file.
description: |
Checks if an image file showing a preview of the item is
available. If not available, a 404 is returned. The preview is
- currently the an image of the first page of the first
- attachment.
+ an image of the first page of the first attachment.
security:
- authTokenHeader: []
parameters:
@@ -2011,6 +2121,7 @@ paths:
404:
description: NotFound
get:
+ operationId: "sec-item-get-preview"
tags: [ Attachment ]
summary: Get a preview image of an attachment file.
description: |
@@ -2036,6 +2147,7 @@ paths:
/sec/item/{id}/customfield:
put:
+ operationId: "sec-item-set-customfield-value"
tags: [ Item ]
summary: Set the value of a custom field.
description: |
@@ -2060,6 +2172,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/item/{itemId}/customfield/{id}:
delete:
+ operationId: "sec-item-delete-customfield-value"
tags: [ Item ]
summary: Removes the value for a custom field
description: |
@@ -2081,6 +2194,7 @@ paths:
/sec/item/{itemId}/reprocess:
post:
+ operationId: "sec-item-start-reprocess"
tags: [ Item ]
summary: Start reprocessing the files of the item.
description: |
@@ -2110,6 +2224,7 @@ paths:
/sec/item/{itemId}/attachment/movebefore:
post:
+ operationId: "sec-item-attach-move-before"
tags: [ Item ]
summary: Reorder attachments within an item
description: |
@@ -2136,6 +2251,7 @@ paths:
/sec/items/deleteAll:
post:
+ operationId: "sec-items-delete-all"
tags:
- Item (Multi Edit)
summary: Delete multiple items.
@@ -2158,6 +2274,7 @@ paths:
/sec/items/tags:
post:
+ operationId: "sec-items-add-all-tags"
tags:
- Item (Multi Edit)
summary: Add tags to multiple items
@@ -2180,30 +2297,8 @@ paths:
application/json:
schema:
$ref: "#/components/schemas/BasicResult"
-
- /sec/items/tagsremove:
- post:
- tags:
- - Item (Multi Edit)
- summary: Remove tags from multiple items
- description: |
- Remove the given tags from all given items.
- security:
- - authTokenHeader: []
- requestBody:
- content:
- application/json:
- schema:
- $ref: "#/components/schemas/ItemsAndRefs"
- responses:
- 200:
- description: Ok
- content:
- application/json:
- schema:
- $ref: "#/components/schemas/BasicResult"
-
put:
+ operationId: "sec-items-replace-all-tags"
tags:
- Item (Multi Edit)
summary: Sets tags to multiple items
@@ -2225,8 +2320,33 @@ paths:
schema:
$ref: "#/components/schemas/BasicResult"
+ /sec/items/tagsremove:
+ post:
+ operationId: "sec-items-remove-all-tags"
+ tags:
+ - Item (Multi Edit)
+ summary: Remove tags from multiple items
+ description: |
+ Remove the given tags from all given items.
+ security:
+ - authTokenHeader: []
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/ItemsAndRefs"
+ responses:
+ 200:
+ description: Ok
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/BasicResult"
+
+
/sec/items/name:
put:
+ operationId: "sec-items-set-name-all"
tags:
- Item (Multi Edit)
summary: Change the name of multiple items
@@ -2250,6 +2370,7 @@ paths:
/sec/items/folder:
put:
+ operationId: "sec-items-set-folder-all"
tags:
- Item (Multi Edit)
summary: Sets a folder to multiple items.
@@ -2274,6 +2395,7 @@ paths:
/sec/items/direction:
put:
+ operationId: "sec-items-set-direction-all"
tags:
- Item (Multi Edit)
summary: Set the direction of multiple items
@@ -2297,6 +2419,7 @@ paths:
/sec/items/date:
put:
+ operationId: "sec-items-set-date-all"
tags:
- Item (Multi Edit)
summary: Set the date of multiple items
@@ -2321,6 +2444,7 @@ paths:
/sec/items/duedate:
put:
+ operationId: "sec-items-set-duedate-all"
tags:
- Item (Multi Edit)
summary: Set the direction of multiple items
@@ -2345,6 +2469,7 @@ paths:
/sec/items/corrOrg:
put:
+ operationId: "sec-items-set-corr-org-all"
tags:
- Item (Multi Edit)
summary: Sets an organization to multiple items.
@@ -2369,6 +2494,7 @@ paths:
/sec/items/corrPerson:
put:
+ operationId: "sec-items-set-corr-person-all"
tags:
- Item (Multi Edit)
summary: Sets an correspondent person to multiple items.
@@ -2393,6 +2519,7 @@ paths:
/sec/items/concPerson:
put:
+ operationId: "sec-items-set-conc-person-all"
tags:
- Item (Multi Edit)
summary: Sets an concerning person to multiple items.
@@ -2417,6 +2544,7 @@ paths:
/sec/items/concEquipment:
put:
+ operationId: "sec-items-set-equip-all"
tags:
- Item (Multi Edit)
summary: Sets an equipment to multiple items.
@@ -2441,6 +2569,7 @@ paths:
/sec/items/confirm:
put:
+ operationId: "sec-items-confirm-all"
tags:
- Item (Multi Edit)
summary: Confirm multiple items.
@@ -2463,6 +2592,7 @@ paths:
/sec/items/unconfirm:
put:
+ operationId: "sec-items-unconfirm-all"
tags:
- Item (Multi Edit)
summary: Un-confirm multiple items.
@@ -2485,6 +2615,7 @@ paths:
/sec/items/reprocess:
post:
+ operationId: "sec-items-reprocess-all"
tags:
- Item (Multi Edit)
summary: Submit multiple items to re-processing
@@ -2511,6 +2642,7 @@ paths:
/sec/items/customfield:
put:
+ operationId: "sec-items-set-customfield-all"
tags: [ Item (Multi Edit) ]
summary: Set the value of a custom field for multiple items
description: |
@@ -2535,6 +2667,7 @@ paths:
/sec/items/customfieldremove:
post:
+ operationId: "sec-items-remove-customfield-all"
tags: [ Item (Multi Edit) ]
summary: Removes the value for a custom field on multiple items
description: |
@@ -2542,8 +2675,6 @@ paths:
items. The field may be specified by its id or name.
security:
- authTokenHeader: []
- parameters:
- - $ref: "#/components/parameters/itemId"
requestBody:
content:
application/json:
@@ -2560,6 +2691,7 @@ paths:
/sec/attachment/{id}:
delete:
+ operationId: "sec-attach-delete-by-id"
tags: [ Attachment ]
summary: Delete an attachment.
description: |
@@ -2582,6 +2714,7 @@ paths:
schema:
$ref: "#/components/schemas/BasicResult"
head:
+ operationId: "sec-attach-check"
tags: [ Attachment ]
summary: Get an attachment file.
description: |
@@ -2609,6 +2742,7 @@ paths:
schema:
type: string
get:
+ operationId: "sec-attach-get"
tags: [ Attachment ]
summary: Get an attachment file.
description: |
@@ -2628,6 +2762,7 @@ paths:
format: binary
/sec/attachment/{id}/original:
head:
+ operationId: "sec-attach-check-original"
tags: [ Attachment ]
summary: Get an attachment file.
description: |
@@ -2658,6 +2793,7 @@ paths:
schema:
type: string
get:
+ operationId: "sec-attach-get-original"
tags: [ Attachment ]
summary: Get an attachment file.
description: |
@@ -2680,6 +2816,7 @@ paths:
format: binary
/sec/attachment/{id}/archive:
head:
+ operationId: "sec-attach-check-archive"
tags: [ Attachment ]
summary: Get an attachment archive file.
description: |
@@ -2710,6 +2847,7 @@ paths:
schema:
type: string
get:
+ operationId: "sec-attach-get-archive"
tags: [ Attachment ]
summary: Get an attachment archive file.
description: |
@@ -2732,6 +2870,7 @@ paths:
format: binary
/sec/attachment/{id}/preview:
head:
+ operationId: "sec-attach-check-preview"
tags: [ Attachment ]
summary: Get a preview image of an attachment file.
description: |
@@ -2747,6 +2886,7 @@ paths:
404:
description: NotFound
get:
+ operationId: "sec-attach-get-preview"
tags: [ Attachment ]
summary: Get a preview image of an attachment file.
description: |
@@ -2770,6 +2910,7 @@ paths:
type: string
format: binary
post:
+ operationId: "sec-attach-regenerate-preview"
tags: [ Attachment ]
summary: (Re)generate a preview image.
description: |
@@ -2789,6 +2930,7 @@ paths:
/sec/attachment/{id}/meta:
get:
+ operationId: "sec-attach-get-meta"
tags: [ Attachment ]
summary: Get the attachment's meta data.
description: |
@@ -2807,6 +2949,7 @@ paths:
$ref: "#/components/schemas/AttachmentMeta"
/sec/attachment/{id}/view:
get:
+ operationId: "sec-attach-show-viewerjs"
tags: [ Attachment ]
summary: A preview of the attachment
description: |
@@ -2828,6 +2971,7 @@ paths:
description: Ok
/sec/attachment/{id}/name:
post:
+ operationId: "sec-attach-set-name"
tags: [ Attachment ]
summary: Changes the name of an attachment
description: |
@@ -2853,6 +2997,7 @@ paths:
/sec/attachments/delete:
post:
+ operationId: "sec-attachs-delete-all"
tags:
- Attachment (Multi Edit)
summary: Delete multiple attachments.
@@ -2875,6 +3020,7 @@ paths:
/sec/queue/state:
get:
+ operationId: "sec-jobs-get-state"
tags: [ Job Queue ]
summary: Get complete state of job queue.
description: |
@@ -2892,6 +3038,7 @@ paths:
$ref: "#/components/schemas/JobQueueState"
/sec/queue/{id}/cancel:
post:
+ operationId: "sec-jobs-cancel-job"
tags: [ Job Queue ]
summary: Cancel a job.
description: |
@@ -2911,6 +3058,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/queue/{id}/priority:
post:
+ operationId: "sec-jobs-set-prio"
tags: [ Job Queue ]
summary: Change the priority of a waiting job.
description: |
@@ -2935,6 +3083,7 @@ paths:
/sec/email/settings/smtp:
get:
+ operationId: "sec-email-settings-smtp-all"
tags: [ E-Mail ]
summary: List email settings for current user.
description: |
@@ -2957,6 +3106,7 @@ paths:
schema:
$ref: "#/components/schemas/EmailSettingsList"
post:
+ operationId: "sec-email-new-smtp-settings"
tags: [ E-Mail ]
summary: Create new email settings
description: |
@@ -2979,6 +3129,7 @@ paths:
parameters:
- $ref: "#/components/parameters/name"
get:
+ operationId: "sec-email-get-smtp-details"
tags: [ E-Mail ]
summary: Return specific email settings by name.
description: |
@@ -2994,6 +3145,7 @@ paths:
schema:
$ref: "#/components/schemas/EmailSettings"
put:
+ operationId: "sec-email-set-smtp-settings"
tags: [ E-Mail ]
summary: Change specific email settings.
description: |
@@ -3013,6 +3165,7 @@ paths:
schema:
$ref: "#/components/schemas/BasicResult"
delete:
+ operationId: "sec-email-delete-smtp-settings"
tags: [ E-Mail ]
summary: Delete e-mail settings.
description: |
@@ -3028,6 +3181,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/email/settings/imap:
get:
+ operationId: "sec-email-imap-settings-all"
tags: [ E-Mail ]
summary: List email settings for current user.
description: |
@@ -3050,6 +3204,7 @@ paths:
schema:
$ref: "#/components/schemas/ImapSettingsList"
post:
+ operationId: "sec-email-new-imap-settings"
tags: [ E-Mail ]
summary: Create new email settings
description: |
@@ -3072,6 +3227,7 @@ paths:
parameters:
- $ref: "#/components/parameters/name"
get:
+ operationId: "sec-email-get-imap-details"
tags: [ E-Mail ]
summary: Return specific email settings by name.
description: |
@@ -3087,6 +3243,7 @@ paths:
schema:
$ref: "#/components/schemas/ImapSettings"
put:
+ operationId: "sec-email-set-imap-settings"
tags: [ E-Mail ]
summary: Change specific email settings.
description: |
@@ -3106,6 +3263,7 @@ paths:
schema:
$ref: "#/components/schemas/BasicResult"
delete:
+ operationId: "sec-email-delete-imap-settings"
tags: [ E-Mail ]
summary: Delete e-mail settings.
description: |
@@ -3122,6 +3280,7 @@ paths:
/sec/email/send/{name}/{id}:
post:
+ operationId: "sec-email-send-with-item"
tags: [ E-Mail ]
summary: Send an email.
description: |
@@ -3147,6 +3306,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/email/sent/item/{id}:
get:
+ operationId: "sec-email-get-sent-mails-to-item"
tags: [ E-Mail ]
summary: Get sent mail related to an item
description: |
@@ -3167,6 +3327,7 @@ paths:
parameters:
- $ref: "#/components/parameters/mailId"
get:
+ operationId: "sec-email-get-sent-mail"
tags: [ E-Mail ]
summary: Get sent single mail related to an item
description: |
@@ -3181,6 +3342,7 @@ paths:
schema:
$ref: "#/components/schemas/SentMail"
delete:
+ operationId: "sec-email-delete-sent-mail"
tags: [ E-Mail ]
summary: Delete a sent mail.
description: |
@@ -3196,6 +3358,7 @@ paths:
$ref: "#/components/schemas/BasicResult"
/sec/calevent/check:
post:
+ operationId: "sec-calevent-check"
tags: [ Utility ]
summary: Check a calendar event string
description: |
@@ -3217,10 +3380,11 @@ paths:
$ref: "#/components/schemas/CalEventCheckResult"
/sec/usertask/notifydueitems:
get:
+ operationId: "sec-usertask-notify-all"
tags: [ User Tasks ]
summary: Get settings for "Notify Due Items" task
description: |
- Return the current notification settings of the authenticated
+ Return all current notification settings of the authenticated
user. Users can be notified on due items via e-mail. This is
done by periodically querying items. It is possible to have
multiple tasks.
@@ -3234,6 +3398,7 @@ paths:
schema:
$ref: "#/components/schemas/NotificationSettingsList"
post:
+ operationId: "sec-usertask-notify-new"
tags: [ User Tasks ]
summary: Create settings for "Notify Due Items" task
description: |
@@ -3254,6 +3419,7 @@ paths:
schema:
$ref: "#/components/schemas/BasicResult"
put:
+ operationId: "sec-usertask-notify-edit"
tags: [ User Tasks ]
summary: Change settings for "Notify Due Items" task
description: |
@@ -3277,7 +3443,9 @@ paths:
parameters:
- $ref: "#/components/parameters/id"
get:
+ operationId: "sec-usertask-notify-get-details"
tags: [ User Tasks ]
+ summary: Get notify items settings for a specific task
description: |
Return the current settings for a single notify-due-items task
of the authenticated user.
@@ -3291,7 +3459,9 @@ paths:
schema:
$ref: "#/components/schemas/NotificationSettings"
delete:
+ operationId: "sec-usertask-notify-delete"
tags: [ User Tasks ]
+ summary: Delete a specific notify due items task
description: |
Delete the settings to a notify-due-items task of the
authenticated user.
@@ -3307,6 +3477,7 @@ paths:
/sec/usertask/notifydueitems/startonce:
post:
+ operationId: "sec-usertask-notify-start-now"
tags: [ User Tasks ]
summary: Start the "Notify Due Items" task once
description: |
@@ -3329,6 +3500,7 @@ paths:
/sec/usertask/scanmailbox:
get:
+ operationId: "sec-usertask-scanmailbox-get-all"
tags: [ User Tasks ]
summary: Get settings for "Scan Mailbox" task
description: |
@@ -3346,6 +3518,7 @@ paths:
schema:
$ref: "#/components/schemas/ScanMailboxSettingsList"
post:
+ operationId: "sec-usertask-scanmailbox-new"
tags: [ User Tasks ]
summary: Create settings for "Scan Mailbox" task
description: |
@@ -3366,6 +3539,7 @@ paths:
schema:
$ref: "#/components/schemas/BasicResult"
put:
+ operationId: "sec-usertask-scanmailbox-edit"
tags: [ User Tasks ]
summary: Change settings for a "Scan Mailbox" task
description: |
@@ -3389,6 +3563,7 @@ paths:
parameters:
- $ref: "#/components/parameters/id"
get:
+ operationId: "sec-usertask-scanmailbox-get-details"
tags: [ User Tasks ]
summary: Get settings for "Scan Mailbox" task
description: |
@@ -3405,6 +3580,7 @@ paths:
schema:
$ref: "#/components/schemas/ScanMailboxSettings"
delete:
+ operationId: "sec-usertask-scanmailbox-delete"
tags: [ User Tasks ]
summary: Delete a scan-mailbox task.
description: |
@@ -3422,6 +3598,7 @@ paths:
/sec/usertask/scanmailbox/startonce:
post:
+ operationId: "sec-usertask-scanmailbox-start-now"
tags: [ User Tasks ]
summary: Start the "Scan Mailbox" task once
description: |
@@ -3444,6 +3621,7 @@ paths:
/sec/customfield:
get:
+ operationId: "sec-customfield-get-all"
tags: [ Custom Fields ]
summary: Get all defined custom fields.
description: |
@@ -3460,6 +3638,7 @@ paths:
schema:
$ref: "#/components/schemas/CustomFieldList"
post:
+ operationId: "sec-customfield-new"
tags: [ Custom Fields ]
summary: Create a new custom field
description: |
@@ -3483,6 +3662,7 @@ paths:
parameters:
- $ref: "#/components/parameters/id"
get:
+ operationId: "sec-customfield-get-details"
tags: [ Custom Fields ]
summary: Get details about a custom field.
description: |
@@ -3497,6 +3677,7 @@ paths:
schema:
$ref: "#/components/schemas/CustomField"
put:
+ operationId: "sec-customfield-edit"
tags: [ Custom Fields ]
summary: Change a custom field
description: |
@@ -3521,6 +3702,7 @@ paths:
schema:
$ref: "#/components/schemas/BasicResult"
delete:
+ operationId: "sec-customfield-delete"
tags: [ Custom Fields ]
summary: Deletes a custom field.
description: |
From b1740fb305318981b318583e2573615e7bc5df5c Mon Sep 17 00:00:00 2001
From: eikek <eike.kettner@posteo.de>
Date: Sat, 12 Jun 2021 21:31:49 +0200
Subject: [PATCH 3/4] Add openapi linting to sbt's lint alias
---
build.sbt | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/build.sbt b/build.sbt
index 013014da..2cbf0eaa 100644
--- a/build.sbt
+++ b/build.sbt
@@ -785,7 +785,7 @@ addCommandAlias("make-pkg", ";clean ;make ;make-zip ;make-deb ;make-tools")
addCommandAlias("ci", "make; lint; test")
addCommandAlias(
"lint",
- "scalafmtSbtCheck; scalafmtCheckAll; Compile/scalafix --check; Test/scalafix --check"
+ "restapi/openapiLint; joexapi/openapiLint; scalafmtSbtCheck; scalafmtCheckAll; Compile/scalafix --check; Test/scalafix --check"
)
addCommandAlias("fix", "Compile/scalafix; Test/scalafix; scalafmtSbt; scalafmtAll")
addCommandAlias("make-website", ";website/clean ;website/zolaBuild ;website/zolaCheck")
From 1ca800a38ecf296126850cc57b10620b21f65353 Mon Sep 17 00:00:00 2001
From: eikek <eike.kettner@posteo.de>
Date: Sat, 12 Jun 2021 21:36:18 +0200
Subject: [PATCH 4/4] Add short text about editing openapi files to dev docs
---
website/site/content/docs/dev/development.md | 20 ++++++++++++++++++++
1 file changed, 20 insertions(+)
diff --git a/website/site/content/docs/dev/development.md b/website/site/content/docs/dev/development.md
index 6044951d..9d2380cb 100644
--- a/website/site/content/docs/dev/development.md
+++ b/website/site/content/docs/dev/development.md
@@ -102,6 +102,26 @@ $ export DOCSPELL_ENV=dev
$ sbt "restserver/reStart"
```
+# Developing Backend
+
+## OpenAPI
+
+The http API is specified in the corresponding `-openapi.yml` file.
+The `component` section is being used to generate code for the client
+and the server, so that both are always in sync. However, the route
+definitions are not checked against the server implementation.
+
+Changes to the openapi files can be checked by running a sbt task:
+
+``` scala
+restapi/openapiLint //and/or
+joexapi/openapiLint
+```
+
+These tasks must not show any errors (it is checked by the CI). The
+warnings should also be fixed.
+
+
# Nix Expressions
The directory `/nix` contains nix expressions to install docspell via