Commit 73e6cf1d authored by Piotr Gawron's avatar Piotr Gawron
Browse files

documentation for comments API call added

parent 117db2cc
......@@ -226,19 +226,7 @@ public class CommentRestImpl extends BaseRestImpl {
private Set<String> createCommentColumnSet(String columns) {
Set<String> columnsSet = new LinkedHashSet<>();
if (columns.equals("")) {
columnsSet.add("title");
columnsSet.add("icon");
columnsSet.add("type");
columnsSet.add("content");
columnsSet.add("removed");
columnsSet.add("coord");
columnsSet.add("modelId");
columnsSet.add("elementId");
columnsSet.add("id");
columnsSet.add("pinned");
columnsSet.add("author");
columnsSet.add("email");
columnsSet.add("removeReason");
columnsSet.addAll(getAvailableChemicalColumns());
} else {
Collections.addAll(columnsSet, columns.split(","));
}
......@@ -300,4 +288,22 @@ public class CommentRestImpl extends BaseRestImpl {
return okStatus();
}
public List<String> getAvailableChemicalColumns() {
List<String> columns = new ArrayList<>();
columns.add("title");
columns.add("icon");
columns.add("type");
columns.add("content");
columns.add("removed");
columns.add("coord");
columns.add("modelId");
columns.add("elementId");
columns.add("id");
columns.add("pinned");
columns.add("author");
columns.add("email");
columns.add("removeReason");
return columns;
}
}
= Rest API Documentation - Project comments
Piotr Gawron
v{project-version} {build-time}
:toc: left
:sectnums:
== Get comments
Get list of comments.
=== CURL sample
include::{snippets}/projects/project_comments/get_all/curl-request.adoc[]
=== Path Parameters
include::{snippets}/projects/project_comments/get_all/path-parameters.adoc[]
=== Request Parameters
include::{snippets}/projects/project_comments/get_all/request-parameters.adoc[]
=== Response Fields
include::{snippets}/projects/project_comments/get_all/response-fields.adoc[]
=== Sample Response
include::{snippets}/projects/project_comments/get_all/response-body.adoc[]
== Get comments for specific reaction
=== CURL sample
include::{snippets}/projects/project_comments/get_reaction/curl-request.adoc[]
=== Path Parameters
include::{snippets}/projects/project_comments/get_reaction/path-parameters.adoc[]
=== Request Parameters
include::{snippets}/projects/project_comments/get_reaction/request-parameters.adoc[]
=== Response Fields
include::{snippets}/projects/project_comments/get_reaction/response-fields.adoc[]
=== Sample Response
include::{snippets}/projects/project_comments/get_reaction/response-body.adoc[]
== Get comments for specific element
=== CURL sample
include::{snippets}/projects/project_comments/get_element/curl-request.adoc[]
=== Path Parameters
include::{snippets}/projects/project_comments/get_element/path-parameters.adoc[]
=== Request Parameters
include::{snippets}/projects/project_comments/get_element/request-parameters.adoc[]
=== Response Fields
include::{snippets}/projects/project_comments/get_element/response-fields.adoc[]
=== Sample Response
include::{snippets}/projects/project_comments/get_element/response-body.adoc[]
== Get comments for specific point
=== CURL sample
include::{snippets}/projects/project_comments/get_point/curl-request.adoc[]
=== Path Parameters
include::{snippets}/projects/project_comments/get_point/path-parameters.adoc[]
=== Request Parameters
include::{snippets}/projects/project_comments/get_point/request-parameters.adoc[]
=== Response Fields
include::{snippets}/projects/project_comments/get_point/response-fields.adoc[]
=== Sample Response
include::{snippets}/projects/project_comments/get_point/response-body.adoc[]
== Create element comment
=== CURL sample
include::{snippets}/projects/project_comments/create_element_comment/curl-request.adoc[]
=== Path Parameters
include::{snippets}/projects/project_comments/create_element_comment/path-parameters.adoc[]
=== Request Parameters
include::{snippets}/projects/project_comments/create_element_comment/request-parameters.adoc[]
=== Response Fields
include::{snippets}/projects/project_comments/create_element_comment/response-fields.adoc[]
=== Sample Response
include::{snippets}/projects/project_comments/create_element_comment/response-body.adoc[]
== Create reaction comment
=== CURL sample
include::{snippets}/projects/project_comments/create_reaction_comment/curl-request.adoc[]
=== Path Parameters
include::{snippets}/projects/project_comments/create_reaction_comment/path-parameters.adoc[]
=== Request Parameters
include::{snippets}/projects/project_comments/create_reaction_comment/request-parameters.adoc[]
=== Response Fields
include::{snippets}/projects/project_comments/create_reaction_comment/response-fields.adoc[]
=== Sample Response
include::{snippets}/projects/project_comments/create_reaction_comment/response-body.adoc[]
== Create coordinates comment
=== CURL sample
include::{snippets}/projects/project_comments/create_point_comment/curl-request.adoc[]
=== Path Parameters
include::{snippets}/projects/project_comments/create_point_comment/path-parameters.adoc[]
=== Request Parameters
include::{snippets}/projects/project_comments/create_point_comment/request-parameters.adoc[]
=== Response Fields
include::{snippets}/projects/project_comments/create_point_comment/response-fields.adoc[]
=== Sample Response
include::{snippets}/projects/project_comments/create_point_comment/response-body.adoc[]
== Delete comment
=== CURL sample
include::{snippets}/projects/project_comments/delete_comment/curl-request.adoc[]
=== Path Parameters
include::{snippets}/projects/project_comments/delete_comment/path-parameters.adoc[]
......@@ -5,7 +5,8 @@ import static org.junit.Assume.assumeTrue;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;
import static org.springframework.restdocs.payload.PayloadDocumentation.*;
import static org.springframework.restdocs.request.RequestDocumentation.*;
import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
import static org.springframework.restdocs.request.RequestDocumentation.requestParameters;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import org.apache.commons.lang3.StringUtils;
......@@ -65,7 +66,7 @@ public class ChemicalControllerIntegrationTest extends ControllerIntegrationTest
mockMvc.perform(request)
.andDo(document("projects/project_chemicals/search_by_query",
pathParameters(parameterWithName("projectId").description("project identifier")),
getProjectPathParameters(),
getChemicalFilter(),
listOfChemicalsFields()))
.andExpect(status().is2xxSuccessful());
......@@ -85,7 +86,7 @@ public class ChemicalControllerIntegrationTest extends ControllerIntegrationTest
String content = mockMvc.perform(request)
.andDo(document("projects/project_chemicals/suggested_query_list",
pathParameters(parameterWithName("projectId").description("project identifier")),
getProjectPathParameters(),
responseFields(
fieldWithPath("[]")
.description("list of suggested chemical queries")
......
package lcsb.mapviewer.web;
import static org.junit.Assert.*;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.*;
import static org.springframework.restdocs.payload.PayloadDocumentation.*;
import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
import static org.springframework.restdocs.request.RequestDocumentation.requestParameters;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import java.util.Arrays;
import java.util.List;
import org.apache.commons.lang3.StringUtils;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.message.BasicNameValuePair;
import org.apache.http.util.EntityUtils;
......@@ -16,6 +22,11 @@ import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.MediaType;
import org.springframework.mock.web.MockHttpSession;
import org.springframework.restdocs.payload.FieldDescriptor;
import org.springframework.restdocs.payload.ResponseFieldsSnippet;
import org.springframework.restdocs.request.PathParametersSnippet;
import org.springframework.restdocs.request.RequestParametersSnippet;
import org.springframework.restdocs.snippet.Snippet;
import org.springframework.test.annotation.Rollback;
import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
import org.springframework.test.web.servlet.RequestBuilder;
......@@ -23,6 +34,8 @@ import org.springframework.transaction.annotation.Transactional;
import com.google.gson.JsonParser;
import lcsb.mapviewer.api.ElementIdentifierType;
import lcsb.mapviewer.api.projects.comments.CommentRestImpl;
import lcsb.mapviewer.common.Configuration;
import lcsb.mapviewer.model.Project;
import lcsb.mapviewer.model.map.Comment;
......@@ -61,6 +74,12 @@ public class CommentControllerIntegrationTest extends ControllerIntegrationTest
@Autowired
private IModelService modelService;
@Autowired
private CommentRestImpl commentRestImpl;
@Autowired
private ProjectSnippets snippets;
@Before
public void setup() {
project = createProject(TEST_PROJECT);
......@@ -81,10 +100,15 @@ public class CommentControllerIntegrationTest extends ControllerIntegrationTest
createComments();
RequestBuilder request = get("/projects/" + TEST_PROJECT + "/comments/models/" + map.getIdModel() + "/")
.session(session);
RequestBuilder request = get(
"/projects/{projectId}/comments/models/{mapId}/?columns=author,elementId,content", TEST_PROJECT, map.getId())
.session(session);
String response = mockMvc.perform(request)
.andDo(document("projects/project_comments/get_all",
getMapPathParameters(),
getCommentsRequestParameters(),
getCommentsResponseFields()))
.andExpect(status().is2xxSuccessful())
.andReturn().getResponse().getContentAsString();
......@@ -93,6 +117,86 @@ public class CommentControllerIntegrationTest extends ControllerIntegrationTest
.getAsJsonArray().size());
}
private ResponseFieldsSnippet getCommentsResponseFields() {
return responseFields(
subsectionWithPath("[]")
.description("list of comments")
.type("Array<Comment>")).andWithPrefix("[].", getCommentResponseFields());
}
private List<FieldDescriptor> getCommentResponseFields() {
return Arrays.asList(
fieldWithPath("author")
.description("author name")
.optional()
.type("String"),
fieldWithPath("owner")
.description("login of the user that created a comment")
.optional()
.type("String"),
fieldWithPath("email")
.description("author email address")
.optional()
.type("String"),
fieldWithPath("content")
.description("content")
.optional()
.type("String"),
fieldWithPath("title")
.description("formatted name of the commented element")
.optional()
.type("String"),
fieldWithPath("pinned")
.description("should the comment be visible to everybody on the map")
.optional()
.type("boolean"),
fieldWithPath("isPinned").ignored(),
fieldWithPath("removed")
.description("is the comment removed")
.optional()
.type("boolean"),
fieldWithPath("removeReason")
.description("reason why comment was removed")
.optional()
.type("String"),
fieldWithPath("id")
.description("comment identifier")
.optional()
.type("integer"),
fieldWithPath("modelId")
.description("map identifier")
.optional()
.type("integer"),
subsectionWithPath("coord")
.description("coordinates where comment should be pinned")
.optional()
.type("Point"),
fieldWithPath("icon")
.description("icon that should be used to visualize this comment")
.optional()
.type("String"),
fieldWithPath("elementId")
.description("element identifier")
.optional()
.type("string"),
fieldWithPath("type")
.description("type of the element that was commented on. Available options "
+ snippets.getOptionsAsString(ElementIdentifierType.class))
.optional()
.type("String"));
}
private RequestParametersSnippet getCommentsRequestParameters() {
return requestParameters(
parameterWithName("columns")
.description("set of columns (all by default). Available options: "
+ StringUtils.join(commentRestImpl.getAvailableChemicalColumns(), ", "))
.optional(),
parameterWithName("removed")
.description("true/false/undefined - when defined comment property must match this parameter")
.optional());
}
@Test
public void testListOfCommentsWithUndefinedProject() throws Exception {
MockHttpSession session = createSession(BUILT_IN_TEST_ADMIN_LOGIN, BUILT_IN_TEST_ADMIN_PASSWORD);
......@@ -261,11 +365,13 @@ public class CommentControllerIntegrationTest extends ControllerIntegrationTest
Comment comment = createComment(map);
commentDao.add(comment);
RequestBuilder request = delete("/projects/" + TEST_PROJECT + "/comments/" + comment.getId() + "/")
.contentType(MediaType.APPLICATION_FORM_URLENCODED)
.session(session);
RequestBuilder request = delete("/projects/{projectId}/comments/{commentId}/",
TEST_PROJECT, comment.getId(), comment.getId())
.session(session);
mockMvc.perform(request)
.andDo(document("projects/project_comments/delete_comment",
getProjectPathParameters().and(parameterWithName("commentId").description("comment identifier"))))
.andExpect(status().is2xxSuccessful());
assertEquals(true, comment.isDeleted());
......@@ -346,11 +452,15 @@ public class CommentControllerIntegrationTest extends ControllerIntegrationTest
commentDao.add(comment);
RequestBuilder request = get(
"/projects/" + TEST_PROJECT + "/comments/models/" + map.getId() + "/bioEntities/reactions/" + reaction.getId())
.contentType(MediaType.APPLICATION_FORM_URLENCODED)
"/projects/{projectId}/comments/models/{mapId}/bioEntities/reactions/{reactionId}",
TEST_PROJECT, map.getId(), reaction.getId())
.session(session);
String response = mockMvc.perform(request)
.andDo(document("projects/project_comments/get_reaction",
getReactionPathParameters(),
getCommentsRequestParameters(),
getCommentsResponseFields()))
.andExpect(status().is2xxSuccessful())
.andReturn().getResponse().getContentAsString();
......@@ -425,11 +535,15 @@ public class CommentControllerIntegrationTest extends ControllerIntegrationTest
commentDao.add(comment);
RequestBuilder request = get(
"/projects/" + TEST_PROJECT + "/comments/models/" + map.getId() + "/bioEntities/elements/" + element.getId())
.contentType(MediaType.APPLICATION_FORM_URLENCODED)
"/projects/{projectId}/comments/models/{mapId}/bioEntities/elements/{elementId}",
TEST_PROJECT, map.getId(), element.getId())
.session(session);
String response = mockMvc.perform(request)
.andDo(document("projects/project_comments/get_element",
getElementPathParameters(),
getCommentsRequestParameters(),
getCommentsResponseFields()))
.andExpect(status().is2xxSuccessful())
.andReturn().getResponse().getContentAsString();
......@@ -438,6 +552,14 @@ public class CommentControllerIntegrationTest extends ControllerIntegrationTest
.getAsJsonArray().size());
}
private PathParametersSnippet getElementPathParameters() {
return getMapPathParameters().and(parameterWithName("elementId").description("element identifier"));
}
private PathParametersSnippet getReactionPathParameters() {
return getMapPathParameters().and(parameterWithName("reactionId").description("reaction identifier"));
}
@Test
public void testGetElementCommentsWithUndefinedProject() throws Exception {
MockHttpSession session = createSession(BUILT_IN_TEST_ADMIN_LOGIN, BUILT_IN_TEST_ADMIN_PASSWORD);
......@@ -504,11 +626,15 @@ public class CommentControllerIntegrationTest extends ControllerIntegrationTest
commentDao.add(comment);
RequestBuilder request = get(
"/projects/" + TEST_PROJECT + "/comments/models/" + map.getId() + "/points/10.00,20.00")
.contentType(MediaType.APPLICATION_FORM_URLENCODED)
"/projects/{projectId}/comments/models/{mapId}/points/{point}",
TEST_PROJECT, map.getId(), "10.00,20.00")
.session(session);
String response = mockMvc.perform(request)
.andDo(document("projects/project_comments/get_point",
getPointPathParameters(),
getCommentsRequestParameters(),
getCommentsResponseFields()))
.andExpect(status().is2xxSuccessful())
.andReturn().getResponse().getContentAsString();
......@@ -517,6 +643,10 @@ public class CommentControllerIntegrationTest extends ControllerIntegrationTest
.getAsJsonArray().size());
}
private PathParametersSnippet getPointPathParameters() {
return getMapPathParameters().and(parameterWithName("point").description("point coordinates"));
}
@Test
public void testGetPointCommentsWithUndefinedProject() throws Exception {
MockHttpSession session = createSession(BUILT_IN_TEST_ADMIN_LOGIN, BUILT_IN_TEST_ADMIN_PASSWORD);
......@@ -590,12 +720,17 @@ public class CommentControllerIntegrationTest extends ControllerIntegrationTest
new BasicNameValuePair("modelId", map.getId().toString()))));
RequestBuilder request = post(
"/projects/" + TEST_PROJECT + "/comments/models/" + map.getId() + "/bioEntities/elements/" + element.getId())
"/projects/{projectId}/comments/models/{mapId}/bioEntities/elements/{elementId}",
TEST_PROJECT, map.getId(), element.getId())
.contentType(MediaType.APPLICATION_FORM_URLENCODED)
.content(body)
.session(session);
mockMvc.perform(request)
.andDo(document("projects/project_comments/create_element_comment",
getElementPathParameters(),
getCreateCommentRequestParameters(),
responseFields(getCommentResponseFields())))
.andExpect(status().is2xxSuccessful());
assertEquals(1, commentDao.getCommentByModel(map, null, null).size());
......@@ -604,6 +739,23 @@ public class CommentControllerIntegrationTest extends ControllerIntegrationTest
assertEquals("Owner of the comment wasn't set properly", user, comment.getUser());
}
private Snippet getCreateCommentRequestParameters() {
return requestParameters(
parameterWithName("modelId")
.description("map identifier"),
parameterWithName("name")
.description("user name"),
parameterWithName("content")
.description("content"),
parameterWithName("email")
.description("user email address"),
parameterWithName("coordinates")
.description("coordinates where comment should be pinned")
.optional(),
parameterWithName("pinned")
.description("should the comment be visible to everybody"));
}
@Test
public void testAddElementCommentAsAnonymous() throws Exception {
String body = EntityUtils.toString(new UrlEncodedFormEntity(Arrays.asList(
......@@ -712,12 +864,17 @@ public class CommentControllerIntegrationTest extends ControllerIntegrationTest
new BasicNameValuePair("modelId", map.getId().toString()))));
RequestBuilder request = post(
"/projects/" + TEST_PROJECT + "/comments/models/" + map.getId() + "/bioEntities/reactions/" + reaction.getId())
"/projects/{projectId}/comments/models/{mapId}/bioEntities/reactions/{reactionId}",
TEST_PROJECT, map.getId(), reaction.getId())
.contentType(MediaType.APPLICATION_FORM_URLENCODED)
.content(body)
.session(session);
mockMvc.perform(request)
.andDo(document("projects/project_comments/create_reaction_comment",
getReactionPathParameters(),
getCreateCommentRequestParameters(),
responseFields(getCommentResponseFields())))
.andExpect(status().is2xxSuccessful());
assertEquals(1, commentDao.getCommentByModel(map, null, null).size());
......@@ -783,12 +940,17 @@ public class CommentControllerIntegrationTest extends ControllerIntegrationTest
new BasicNameValuePair("modelId", map.getId().toString()))));
RequestBuilder request = post(
"/projects/" + TEST_PROJECT + "/comments/models/" + map.getId() + "/points/10,2")
"/projects/{projectId}/comments/models/{mapId}/points/{point}",
TEST_PROJECT, map.getId(), "10,2")
.contentType(MediaType.APPLICATION_FORM_URLENCODED)
.content(body)
.session(session);
mockMvc.perform(request)
.andDo(document("projects/project_comments/create_point_comment",
getPointPathParameters(),
getCreateCommentRequestParameters(),
responseFields(getCommentResponseFields())))
.andExpect(status().is2xxSuccessful());
assertEquals(1, commentDao.getCommentByModel(map, null, null).size());
......
package lcsb.mapviewer.web;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
import static org.springframework.restdocs.request.RequestDocumentation.pathParameters;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
......@@ -25,6 +27,7 @@ import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.mock.web.MockHttpSession;
import org.springframework.restdocs.JUnitRestDocumentation;
import org.springframework.restdocs.operation.preprocess.Preprocessors;
import org.springframework.restdocs.request.PathParametersSnippet;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.test.context.ContextConfiguration;
import org.springframework.test.context.web.WebAppConfiguration;
......@@ -226,7 +229,7 @@ abstract public class ControllerIntegrationTest {
User admin = userService.getUserByLogin(BUILT_IN_TEST_ADMIN_LOGIN);
Project project = new Project(projectId);
project.setOwner(admin);
UploadedFileEntry file = createFile(Files.readAllBytes(Paths.get("./src/test/resources/empty.png")), admin);
UploadedFileEntry file = createFile(Files.readAllBytes(Paths.get("./src/test/resources/empty.png")), admin);
ModelData map = new ModelData();
map.setTileSize(256);
map.setWidth(100);
......@@ -521,4 +524,12 @@ abstract public class ControllerIntegrationTest {
return comment;
}
protected PathParametersSnippet getProjectPathParameters() {
return pathParameters(parameterWithName("projectId").description("project identifier"));
}
protected PathParametersSnippet getMapPathParameters() {
return getProjectPathParameters().and(parameterWithName("mapId").description("map identifier"));
}
}
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment