Merge pull request #874 from eikek/api-docs

Api docs fixes and nicer design

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)
 
@@ -784,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")

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: |

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")

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