Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Merged
merged 8 commits into from Sep 13, 2022
Merged

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

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
bf6c163
remove swaggerAkkaHttp dependency
mpro7 Sep 12, 2022
6668496
remove SwaggerApiDocsRoute and its usage
mpro7 Sep 12, 2022
93e0133
remove Swagger related documentation
mpro7 Sep 12, 2022
3ff4703
remove other docs annotations
mpro7 Sep 12, 2022
89896df
docs folder cleanup
mpro7 Sep 13, 2022
26e0092
fix failing docs test
mpro7 Sep 13, 2022
367938e
to make codacy happy
mpro7 Sep 13, 2022
114125a
one more time
mpro7 Sep 13, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
5 changes: 1 addition & 4 deletions .scala-steward.conf
View file
Open in desktop
@@ -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" }
]
10 changes: 0 additions & 10 deletions docs/03-apis/api-admin/introduction.md
View file
Open in desktop
Expand Up @@ -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
1 change: 0 additions & 1 deletion docs/Readme.md
View file
Open in desktop
Expand Up @@ -9,7 +9,6 @@ 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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This whole structure is not up-to-date. Could you go over the whole Readme.md file if you touch it anyway?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Although it's out of the scope of this PR I cleaned it up. There should be another task defined to clean the whole API documentation though.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And I removed too much :)
Do we actually need this "test"?

  test-docs-build:
    name: Test docs
    runs-on: ubuntu-latest
    steps:
      - name: Checkout source
        uses: actions/checkout@v3
      - name: Install requirements (pip, npm, apt)
        run: |
          python -m pip install --upgrade pip
          pip install -r docs/requirements.txt
          npm install --global typedoc
          sudo apt-get install graphviz
      - name: Build docs
        run: make docs-build

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, we need it. It's to make sure that the docs compile.


All the different documentations are build by invoking the following make
commands from the project root directory:
Expand Down
28 changes: 13 additions & 15 deletions project/Dependencies.scala
View file
Open in desktop
Expand Up @@ -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
Expand Down Expand Up @@ -148,7 +147,6 @@ object Dependencies {
slf4jApi,
springSecurityCore,
bouncyCastle,
swaggerAkkaHttp,
testcontainers % Test,
titaniumJSONLD,
xmlunitCore % Test,
Expand Down
28 changes: 0 additions & 28 deletions webapi/src/main/scala/org/knora/webapi/annotation/ApiMayChange.scala
View file
Open in desktop

This file was deleted.

13 changes: 0 additions & 13 deletions webapi/src/main/scala/org/knora/webapi/annotation/ProjectUnique.scala
View file
Open in desktop

This file was deleted.

13 changes: 0 additions & 13 deletions webapi/src/main/scala/org/knora/webapi/annotation/ServerUnique.scala
View file
Open in desktop

This file was deleted.

18 changes: 6 additions & 12 deletions ...cala/org/knora/webapi/messages/admin/responder/projectsmessages/ProjectsMessagesADM.scala
View file
Open in desktop
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -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.
Expand All @@ -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],
Expand Down Expand Up @@ -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)

/**
Expand Down
3 changes: 0 additions & 3 deletions webapi/src/main/scala/org/knora/webapi/responders/admin/ProjectsResponderADM.scala
View file
Open in desktop
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
4 changes: 1 addition & 3 deletions webapi/src/main/scala/org/knora/webapi/routing/ApiRoutes.scala
View file
Open in desktop
Expand Up @@ -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
Expand Down Expand Up @@ -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
}
}
}
Expand Down
60 changes: 0 additions & 60 deletions webapi/src/main/scala/org/knora/webapi/routing/SwaggerApiDocsRoute.scala
View file
Open in desktop

This file was deleted.

5 changes: 0 additions & 5 deletions webapi/src/main/scala/org/knora/webapi/routing/admin/GroupsRouteADM.scala
View file
Open in desktop
Expand Up @@ -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._
Expand All @@ -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
Expand Down