From 9f69d7675ca19c2a950e376bb8191ea102c9b1c7 Mon Sep 17 00:00:00 2001 From: Joris Borgdorff Date: Tue, 1 Oct 2019 17:02:27 +0200 Subject: [PATCH] Some documentation --- README.md | 15 ++++++++++++++- .../org/radarbase/auth/jersey/ProjectService.kt | 9 +++++++++ 2 files changed, 23 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d8e2ec2..5b41a93 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,17 @@ Library to facilitate OAuth 2.0 integration with a Jersey-based REST API. # Usage +Add this library to your project using the following Gradle configuration: +```gradle +repositories { + maven { url "https://dl.bintray.com/radar-base/org.radarbase" } +} + +dependencies { + api("org.radarbase:radar-auth-jersey:0.1.0") +} +``` + Any path or resource that should be authenticated against the ManagementPortal, should be annotated with `@Authenticated`. Specific authorization can be checked by adding a `@NeedsPermission` annotation. An `Auth` object can be injected to get app-specific information. Examples: ```kotlin @@ -34,7 +45,7 @@ class Users(@Context projectService: ProjectService) { } ``` -These APIs can be activated by implementing the `ProjectService` that ensures that a project exists and by running, during ResourceConfig setup: +These APIs are activated by adding `JerseyResourceEnhancer` implementations to your resource definition: ```kotlin val authConfig = AuthConfig( managementPortalUrl = "http://...", @@ -58,6 +69,8 @@ resourceConfig.register(object : AbstractBinder() { }) ``` +Ensure that a class implementing `org.radarbase.auth.jersey.ProjectService` is added to the binder. + ## Error handling This package adds some error handling. Specifically, `org.radarbase.auth.jersey.exception.HttpApplicationException` can be used and extended to serve detailed error messages with customized logging and HTML templating. They can be thrown from any resource. diff --git a/src/main/kotlin/org/radarbase/auth/jersey/ProjectService.kt b/src/main/kotlin/org/radarbase/auth/jersey/ProjectService.kt index 4fd8582..a6b49a3 100644 --- a/src/main/kotlin/org/radarbase/auth/jersey/ProjectService.kt +++ b/src/main/kotlin/org/radarbase/auth/jersey/ProjectService.kt @@ -9,6 +9,15 @@ package org.radarbase.auth.jersey +import org.radarbase.auth.jersey.exception.HttpApplicationException + +/** + * Service to keep track of active projects. + */ interface ProjectService { + /** + * Ensure that given project ID is valid. + * @throws HttpApplicationException if the project ID is not a valid project ID. + */ fun ensureProject(projectId: String) }