From 36f72e40607262775449de9a8d8dc5168b2e666e Mon Sep 17 00:00:00 2001 From: Gavriella Date: Sat, 24 Aug 2024 08:54:03 -0600 Subject: [PATCH] issue-29616-authentication-endpoint-documentation (#29617) ### Proposed Changes * `v1/authentication` endpoint documentation * `v1/authentication/api-token` documentation * `v1/authentication/logInUser` documentation ### Checklist - [ ] Tests - [ ] Translations - [ ] Security Implications Contemplated (add notes if applicable) ### Additional Info ** any additional useful context or info ** ### Screenshots Original | Updated :-------------------------:|:-------------------------: ** original screenshot ** | ** updated screenshot ** --- .../AuthenticationResource.java | 63 ++++++++++++++++++- .../CreateJsonWebTokenResource.java | 13 ++++ .../ResponseEntityUserMapView.java | 9 +++ .../ResponseEntityUserView.java | 9 +++ 4 files changed, 93 insertions(+), 1 deletion(-) create mode 100644 dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/ResponseEntityUserMapView.java create mode 100644 dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/ResponseEntityUserView.java diff --git a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java index 35b6b1c59a7f..2a25bc99df80 100644 --- a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java +++ b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java @@ -26,6 +26,16 @@ import com.liferay.portal.model.User; import com.liferay.portal.util.WebKeys; import com.liferay.util.LocaleUtil; +import io.swagger.v3.oas.annotations.tags.Tag; +import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.Parameter; +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.ExampleObject; +import io.swagger.v3.oas.annotations.media.Schema; +import io.swagger.v3.oas.annotations.parameters.RequestBody; +import io.swagger.v3.oas.annotations.responses.ApiResponse; +import io.swagger.v3.oas.annotations.responses.ApiResponses; +import io.swagger.v3.oas.annotations.ExternalDocumentation; import java.io.Serializable; import java.util.Date; import java.util.List; @@ -34,6 +44,7 @@ import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import javax.servlet.http.HttpSession; +import javax.ws.rs.Consumes; import javax.ws.rs.GET; import javax.ws.rs.POST; import javax.ws.rs.Path; @@ -52,8 +63,15 @@ * @version 3.7 * @since Jul 7, 2016 */ + + @SuppressWarnings("serial") @Path("/v1/authentication") +@Tag(name = "Authentication", + description = "Endpoints that perform operations related to user authentication", + externalDocs = @ExternalDocumentation(description = "Additional Authentication API information", + url = "https://www.dotcms.com/docs/latest/rest-api-authentication")) + public class AuthenticationResource implements Serializable { static final String USER = "user"; @@ -90,8 +108,37 @@ protected AuthenticationResource(final LoginServiceAPI loginService, @JSONP @NoCache @Produces({MediaType.APPLICATION_JSON, "application/javascript"}) - public final Response authentication(@Context final HttpServletRequest request, + @Consumes({MediaType.APPLICATION_JSON}) + @Operation(operationId = "postAuthentication", + summary = "Verifies user or application authentication", + description = "Takes a user's login ID and password and checks them against the user rolls.\n\n" + + "If the user is found and authenticated, a session is created.\n\n" + + "Otherwise the system will return an 'authentication failed' message.\n\n", + tags = {"Authentication"}, + responses = { + @ApiResponse(responseCode = "200", description = "User authentication successful", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ResponseEntityUserMapView.class))), + @ApiResponse(responseCode = "401", description = "User not authenticated"), + @ApiResponse(responseCode = "403", description = "Forbidden request"), + @ApiResponse(responseCode = "500", description = "Unexpected error") + } + ) + public final Response authentication( + @Context final HttpServletRequest request, @Context final HttpServletResponse response, + @RequestBody(description = "This method takes a user's credentials and language preferences to authenticate them.\n\n" + + "Requires a POST body consisting of a JSON object containing the following properties:\n\n" + + "| **Property** | **Value** | **Description** |\n" + + "|--------------|-----------|-----------------------------------------------|\n" + + "| `userId` | String | **Required.** ID of user attempting to log in |\n" + + "| `password` | String | User password |\n" + + "| `language` | String | Preferred language for user |\n" + + "| `country` | String | Country where user is located |\n", + required = true, + content = @Content( + schema = @Schema(implementation = AuthenticationForm.class) + )) final AuthenticationForm authenticationForm) { Response res = null; @@ -168,6 +215,20 @@ public final Response authentication(@Context final HttpServletRequest request, @JSONP @NoCache @Produces({MediaType.APPLICATION_JSON, "application/javascript"}) + @Operation(operationId = "getLogInUser", + summary = "Retrieves user data", + description = "Provides information about any users that are currently in a session.\n\n" + + "This retrieved data will be formatted into a JSON response body.\n\n", + tags = {"Authentication"}, + responses = { + @ApiResponse(responseCode = "200", description = "User data successfully collected", + content = @Content( + schema = @Schema(implementation = ResponseEntityUserView.class) + )), + @ApiResponse(responseCode = "400", description = "Bad request"), + @ApiResponse(responseCode = "401", description = "Unauthorized request"), + @ApiResponse(responseCode = "404", description = "User not found") + }) @Path("logInUser") public final Response getLoginUser(@Context final HttpServletRequest request){ Response res = null; diff --git a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/CreateJsonWebTokenResource.java b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/CreateJsonWebTokenResource.java index 29b67bc1cb94..bc07561ac923 100644 --- a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/CreateJsonWebTokenResource.java +++ b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/CreateJsonWebTokenResource.java @@ -32,6 +32,17 @@ import com.liferay.portal.model.User; import com.liferay.portal.util.PortalUtil; import com.liferay.util.LocaleUtil; +import io.swagger.v3.oas.annotations.Hidden; +import io.swagger.v3.oas.annotations.tags.Tag; +import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.Parameter; +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.ExampleObject; +import io.swagger.v3.oas.annotations.media.Schema; +import io.swagger.v3.oas.annotations.parameters.RequestBody; +import io.swagger.v3.oas.annotations.responses.ApiResponse; +import io.swagger.v3.oas.annotations.responses.ApiResponses; +import io.swagger.v3.oas.annotations.ExternalDocumentation; import org.elasticsearch.common.collect.Map; import org.glassfish.jersey.server.JSONP; @@ -98,6 +109,8 @@ protected CreateJsonWebTokenResource(final LoginServiceAPI loginService, @JSONP @NoCache @Produces({MediaType.APPLICATION_JSON, "application/javascript"}) + @Deprecated + @Hidden //not shown in API playground public final Response getApiToken(@Context final HttpServletRequest request, @Context final HttpServletResponse response, final CreateTokenForm createTokenForm) { diff --git a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/ResponseEntityUserMapView.java b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/ResponseEntityUserMapView.java new file mode 100644 index 000000000000..296f8c8e00e3 --- /dev/null +++ b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/ResponseEntityUserMapView.java @@ -0,0 +1,9 @@ +package com.dotcms.rest.api.v1.authentication; + +import com.dotcms.rest.ResponseEntityView; + +public class ResponseEntityUserMapView extends ResponseEntityView { + public ResponseEntityUserMapView(AuthenticationForm entity) { + super(entity); + } +} diff --git a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/ResponseEntityUserView.java b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/ResponseEntityUserView.java new file mode 100644 index 000000000000..bf967536a7b3 --- /dev/null +++ b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/ResponseEntityUserView.java @@ -0,0 +1,9 @@ +package com.dotcms.rest.api.v1.authentication; + +import com.dotcms.rest.ResponseEntityView; + +public class ResponseEntityUserView extends ResponseEntityView { + public ResponseEntityUserView(AuthenticationForm entity) { + super(entity); + } +}