refactor: remove swagger route and docs annotations (DEV-1335) (#2203)

.scala-steward.conf

@@ -1,8 +1,5 @@
 # ignore the following dependencies:
-
 # jodd -> hard to update and only used in DateUtilV1
-# swagger-akka-http -> should be removed in separate PR
 updates.ignore = [
-        { groupId = "org.jodd", artifactId="jodd", version = "3.2.7" },
-        { groupId = "com.github.swagger-akka-http", artifactId="swagger-akka-http", version = "1.6.0" }
+        { groupId = "org.jodd", artifactId="jodd", version = "3.2.7" }
     ]

docs/03-apis/api-admin/introduction.md

@@ -52,16 +52,6 @@ API server can authenticate the user making the request. Credentials can
 be sent as a part of the HTTP header or as parts of the URL (see
 [Authentication in Knora](../../05-internals/design/principles/authentication.md)).
 
-## OpenAPI/Swagger
-
-The Admin API uses
-[OpenAPI](https://github.com/OAI/OpenAPI-Specification) for
-documentation purposes. To try it out, run webapi and open
-http://host/api-docs/swagger.json in <http://petstore.swagger.io> .
-Alternatively, the documentation can be looked at by using
-[ReDoc](https://github.com/Rebilly/ReDoc), which is provided in
-`knora/docs/redoc/index.html` and is published under <https://docs.knora.org/api-admin/index.html>.
-
 ## Admin API Endpoints
 
 TODO

docs/Readme.md

@@ -1,47 +1,26 @@
 # DSP-API Documentation
 
-## MkDocs Documentation
+This folder contains the sources to the DSP-API part of documentation published
+under <https://docs.dasch.swiss/> and managed by
+[DSP-DOCS](https://github.com/dasch-swiss/dsp-docs) repository.
 
-This folder contains the sources to the DSP-API documentation website published
-under <https://docs.dasch.swiss/>
+## Build and serve the docs locally
 
-The `src` folder contains the following documentation sources:
-
-- `src/api-v1`: The DSP-API V1 (JSON) Request and Response Format documentation. Source can be found in `salsah1/src/typescript_interfaces`
-- `src/api-v2`: The DSP-API V2 (JSON-LD) Request and Response Format documentation.
-- `src/api-admin`: The DSP-API Admin (JSON) Request and Response format Swagger-based documentation.
-
-All the different documentations are build by invoking the following make
-commands from the project root directory:
+Documentation can be build by invoking the following make commands from
+the project root directory:
 
 ```shell
+make docs-install-requirements: ## install requirements
 make docs-build # build the documentation
 make docs-serve # serve it locally
-make docs-publish # publish it do Github pages
-make docs-install-requirements: ## install requirements
 ```
 
-This command will build all documentation and publish it to the `gh-pages` branch.
-
-## Prerequisites
+### Prerequisites
 
-1. You will need [Graphviz](http://www.graphviz.org/). On macOS:
+You will need [Graphviz](http://www.graphviz.org/). On macOS:
 
     ```shell
     brew install graphviz
     ```
 
     On Linux, use your distribution's package manager.
-
-1. The DSP-API V1 / V2 Request and Response Format documentation is
-formally described using typescript interfaces. To create the documentation
-from these interfaces, we use `typedoc`.
-
-    Install `typedoc` using `npm`:
-
-    ```shell
-    npm install --global typedoc
-    ```
-
-    If you do not have `npm` (node package manager), install it first. You will
-    find more information about `npm` here: <https://www.npmjs.com/>.

project/Dependencies.scala

@@ -84,20 +84,19 @@ object Dependencies {
   val chill = "com.twitter" %% "chill" % "0.10.0" // Scala 3 incompatible
 
   // other
-  val diff            = "com.sksamuel.diff"             % "diff"              % "1.1.11"
-  val gwtServlet      = "com.google.gwt"                % "gwt-servlet"       % "2.10.0"
-  val icu4j           = "com.ibm.icu"                   % "icu4j"             % "71.1"
-  val jakartaJSON     = "org.glassfish"                 % "jakarta.json"      % "2.0.1"
-  val jodd            = "org.jodd"                      % "jodd"              % "3.2.7"
-  val rdf4jClient     = "org.eclipse.rdf4j"             % "rdf4j-client"      % "4.1.0"
-  val rdf4jShacl      = "org.eclipse.rdf4j"             % "rdf4j-shacl"       % "4.1.0"
-  val saxonHE         = "net.sf.saxon"                  % "Saxon-HE"          % "11.4"
-  val scalaGraph      = "org.scala-graph"              %% "graph-core"        % "1.13.5" // Scala 3 incompatible
-  val scallop         = "org.rogach"                   %% "scallop"           % "4.1.0"  // Scala 3 compatible
-  val swaggerAkkaHttp = "com.github.swagger-akka-http" %% "swagger-akka-http" % "1.6.0"  // Scala 3 incompatible
-  val titaniumJSONLD  = "com.apicatalog"                % "titanium-json-ld"  % "1.3.1"
-  val xmlunitCore     = "org.xmlunit"                   % "xmlunit-core"      % "2.9.0"
-  val jacksonDatabind = "com.fasterxml.jackson.core"    % "jackson-databind"  % "2.13.4"
+  val diff            = "com.sksamuel.diff"          % "diff"             % "1.1.11"
+  val gwtServlet      = "com.google.gwt"             % "gwt-servlet"      % "2.10.0"
+  val icu4j           = "com.ibm.icu"                % "icu4j"            % "71.1"
+  val jakartaJSON     = "org.glassfish"              % "jakarta.json"     % "2.0.1"
+  val jodd            = "org.jodd"                   % "jodd"             % "3.2.7"
+  val rdf4jClient     = "org.eclipse.rdf4j"          % "rdf4j-client"     % "4.1.0"
+  val rdf4jShacl      = "org.eclipse.rdf4j"          % "rdf4j-shacl"      % "4.1.0"
+  val saxonHE         = "net.sf.saxon"               % "Saxon-HE"         % "11.4"
+  val scalaGraph      = "org.scala-graph"           %% "graph-core"       % "1.13.5" // Scala 3 incompatible
+  val scallop         = "org.rogach"                %% "scallop"          % "4.1.0"  // Scala 3 compatible
+  val titaniumJSONLD  = "com.apicatalog"             % "titanium-json-ld" % "1.3.1"
+  val xmlunitCore     = "org.xmlunit"                % "xmlunit-core"     % "2.9.0"
+  val jacksonDatabind = "com.fasterxml.jackson.core" % "jackson-databind" % "2.13.4"
 
   // test
   val akkaHttpTestkit      = "com.typesafe.akka"    %% "akka-http-testkit"         % AkkaHttpVersion  // Scala 3 incompatible
@@ -148,7 +147,6 @@ object Dependencies {
     slf4jApi,
     springSecurityCore,
     bouncyCastle,
-    swaggerAkkaHttp,
     testcontainers % Test,
     titaniumJSONLD,
     xmlunitCore % Test,

webapi/src/main/scala/org/knora/webapi/messages/admin/responder/projectsmessages/ProjectsMessagesADM.scala

@@ -20,8 +20,6 @@ import dsp.errors.DataConversionException
 import dsp.errors.OntologyConstraintException
 import dsp.valueobjects.V2
 import org.knora.webapi.IRI
-import org.knora.webapi.annotation.ApiMayChange
-import org.knora.webapi.annotation.ServerUnique
 import org.knora.webapi.messages.ResponderRequest.KnoraRequestADM
 import org.knora.webapi.messages.StringFormatter
 import org.knora.webapi.messages.admin.responder.KnoraResponseADM
@@ -247,7 +245,6 @@ case class ProjectKeywordsGetRequestADM(
  * @param identifier           the identifier of the project.
  * @param requestingUser       the user making the request.
  */
-@ApiMayChange
 case class ProjectRestrictedViewSettingsGetADM(
   identifier: ProjectIdentifierADM,
   requestingUser: UserADM
@@ -259,7 +256,6 @@ case class ProjectRestrictedViewSettingsGetADM(
  * @param identifier           the identifier of the project.
  * @param requestingUser       the user making the request.
  */
-@ApiMayChange
 case class ProjectRestrictedViewSettingsGetRequestADM(
   identifier: ProjectIdentifierADM,
   requestingUser: UserADM
@@ -365,11 +361,10 @@ case class ProjectKeywordsGetResponseADM(keywords: Seq[String]) extends KnoraRes
 }
 
 /**
- * API MAY CHANGE: Represents a response to a request for the project's restricted view settings.
+ * Represents a response to a request for the project's restricted view settings.
  *
  * @param settings the restricted view settings.
  */
-@ApiMayChange
 case class ProjectRestrictedViewSettingsGetResponseADM(settings: ProjectRestrictedViewSettingsADM)
     extends KnoraResponseADM
     with ProjectsADMJsonProtocol {
@@ -399,8 +394,8 @@ case class ProjectDataGetResponseADM(projectDataFile: Path)
  * Represents basic information about a project.
  *
  * @param id          The project's IRI.
- * @param shortname   The project's shortname. [[ServerUnique]].
- * @param shortcode   The project's shortcode. [[ServerUnique]].
+ * @param shortname   The project's shortname.
+ * @param shortcode   The project's shortcode.
  * @param longname    The project's long name.
  * @param description The project's description.
  * @param keywords    The project's keywords.
@@ -411,8 +406,8 @@ case class ProjectDataGetResponseADM(projectDataFile: Path)
  */
 case class ProjectADM(
   id: IRI,
-  @ServerUnique shortname: String,
-  @ServerUnique shortcode: String,
+  shortname: String,
+  shortcode: String,
   longname: Option[String],
   description: Seq[StringLiteralV2],
   keywords: Seq[String],
@@ -639,12 +634,11 @@ object ProjectIdentifierType {
 }
 
 /**
- * API MAY CHANGE: Represents the project's restricted view settings.
+ * Represents the project's restricted view settings.
  *
  * @param size      the restricted view size.
  * @param watermark the watermark file.
  */
-@ApiMayChange
 case class ProjectRestrictedViewSettingsADM(size: Option[String] = None, watermark: Option[String] = None)
 
 /**

webapi/src/main/scala/org/knora/webapi/responders/admin/ProjectsResponderADM.scala

@@ -20,7 +20,6 @@ import scala.util.Try
 
 import dsp.errors._
 import org.knora.webapi._
-import org.knora.webapi.annotation.ApiMayChange
 import org.knora.webapi.instrumentation.InstrumentationSupport
 import org.knora.webapi.messages.IriConversions._
 import org.knora.webapi.messages.OntologyConstants
@@ -686,7 +685,6 @@ class ProjectsResponderADM(responderData: ResponderData) extends Responder(respo
    * @param requestingUser       the user making the request.
    * @return [[ProjectRestrictedViewSettingsADM]]
    */
-  @ApiMayChange
   private def projectRestrictedViewSettingsGetADM(
     identifier: ProjectIdentifierADM,
     requestingUser: UserADM
@@ -738,7 +736,6 @@ class ProjectsResponderADM(responderData: ResponderData) extends Responder(respo
    * @param requestingUser the user making the request.
    * @return [[ProjectRestrictedViewSettingsGetResponseADM]]
    */
-  @ApiMayChange
   private def projectRestrictedViewSettingsGetRequestADM(
     identifier: ProjectIdentifierADM,
     requestingUser: UserADM

webapi/src/main/scala/org/knora/webapi/routing/ApiRoutes.scala

@@ -20,7 +20,6 @@ import org.knora.webapi.routing.AroundDirectives
 import org.knora.webapi.routing.HealthRoute
 import org.knora.webapi.routing.KnoraRouteData
 import org.knora.webapi.routing.RejectingRoute
-import org.knora.webapi.routing.SwaggerApiDocsRoute
 import org.knora.webapi.routing.VersionRoute
 import org.knora.webapi.routing.admin.FilesRouteADM
 import org.knora.webapi.routing.admin.GroupsRouteADM
@@ -117,8 +116,7 @@ private final case class ApiRoutesImpl(routeData: KnoraRouteData, runtime: Runti
                 new ProjectsRouteADM(routeData).makeRoute ~
                 new StoreRouteADM(routeData).makeRoute ~
                 new UsersRouteADM(routeData).makeRoute ~
-                new FilesRouteADM(routeData).makeRoute ~
-                new SwaggerApiDocsRoute(routeData).makeRoute
+                new FilesRouteADM(routeData).makeRoute
             }
           }
         }

webapi/src/main/scala/org/knora/webapi/routing/admin/GroupsRouteADM.scala

@@ -8,11 +8,9 @@ package org.knora.webapi.routing.admin
 import akka.http.scaladsl.server.Directives._
 import akka.http.scaladsl.server.PathMatcher
 import akka.http.scaladsl.server.Route
-import io.swagger.annotations._
 import zio.prelude.Validation
 
 import java.util.UUID
-import javax.ws.rs.Path
 
 import dsp.errors.BadRequestException
 import dsp.valueobjects.Group._
@@ -26,9 +24,6 @@ import org.knora.webapi.routing.RouteUtilADM
 /**
  * Provides a routing function for API routes that deal with groups.
  */
-
-@Api(value = "groups", produces = "application/json")
-@Path("/admin/groups")
 class GroupsRouteADM(routeData: KnoraRouteData)
     extends KnoraRoute(routeData)
     with Authenticator