Commit 3003782d authored by Piotr Gawron's avatar Piotr Gawron
Browse files

doc for uploading simple project

parent 2f1cf991
= Rest API Documentation
= Rest API Documentation - Authentication
Piotr Gawron
v{project-version} {build-time}
:toc: left
:sectnums:
== Authentication
=== Login
== Login
Login to the system. If credentials are invalid response with 403 status code will be returned. Token will be valid for the next 120 minutes.
==== CURL sample
=== CURL sample
include::{snippets}/authentication/login/curl-request.adoc[]
==== Request Parameters
=== Request Parameters
include::{snippets}/authentication/login/request-parameters.adoc[]
==== Response Fields
=== Response Fields
include::{snippets}/authentication/login/response-fields.adoc[]
==== Sample Response
=== Sample Response
include::{snippets}/authentication/login/response-body.adoc[]
=== Logout
== Logout
Logout from the system.
==== CURL sample
=== CURL sample
include::{snippets}/authentication/logout/curl-request.adoc[]
==== Response Fields
=== Response Fields
include::{snippets}/authentication/logout/response-fields.adoc[]
==== Sample Response
=== Sample Response
include::{snippets}/authentication/logout/response-body.adoc[]
=== Check if session is still valid
== Check if session is still valid
Sometimes there is need for verification if user is authenticated in the current session (for instance we might need this information to check if our session did not expire). This API call returns information if the session is still valid.
==== CURL sample
=== CURL sample
include::{snippets}/authentication/isSessionValid/curl-request.adoc[]
==== Response Fields
=== Response Fields
include::{snippets}/authentication/isSessionValid/response-fields.adoc[]
==== Sample Response
=== Sample Response
include::{snippets}/authentication/isSessionValid/response-body.adoc[]
= Rest API Documentation
= Rest API Documentation - Projects
Piotr Gawron
v{project-version} {build-time}
:toc: left
:sectnums:
== Projects
=== Get project
== Get project
Returns meta data of the project.
==== CURL sample
=== CURL sample
include::{snippets}/projects/project_data/get_project/curl-request.adoc[]
==== Request Parameters
include::{snippets}/projects/project_data/get_project/request-parameters.adoc[]
=== Path Parameters
include::{snippets}/projects/project_data/get_project/path-parameters.adoc[]
==== Response Fields
=== Response Fields
include::{snippets}/projects/project_data/get_project/response-fields.adoc[]
==== Sample Response
=== Sample Response
include::{snippets}/projects/project_data/get_project/response-body.adoc[]
=== List
== List
List all projects.
==== CURL sample
=== CURL sample
include::{snippets}/projects/project_data/list/curl-request.adoc[]
==== Request Parameters
include::{snippets}/projects/project_data/list/request-parameters.adoc[]
==== Response Fields
=== Response Fields
include::{snippets}/projects/project_data/list/response-fields.adoc[]
==== Sample Response
=== Sample Response
include::{snippets}/projects/project_data/list/response-body.adoc[]
== Create project
Creates project from file that is already uploaded to minerva.
=== Path Parameters
include::{snippets}/projects/project_data/create_simple/path-parameters.adoc[]
=== Request Parameters
include::{snippets}/projects/project_data/create_simple/request-parameters.adoc[]
=== Response Fields
include::{snippets}/projects/project_data/create_simple/response-fields.adoc[]
=== Example 1.
Upload of project from simple file
==== CURL sample
include::{snippets}/projects/project_data/create_simple/curl-request.adoc[]
==== Sample Response
include::{snippets}/projects/project_data/create_simple/response-body.adoc[]
=== Example 2.
Upload of project from complex zip file
==== CURL sample
include::{snippets}/projects/project_data/create_zip/curl-request.adoc[]
==== Sample Response
include::{snippets}/projects/project_data/create_zip/response-body.adoc[]
package lcsb.mapviewer.web;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
......@@ -18,6 +19,7 @@ import org.junit.*;
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.security.crypto.password.PasswordEncoder;
import org.springframework.test.context.ContextConfiguration;
import org.springframework.test.context.web.WebAppConfiguration;
......@@ -102,14 +104,16 @@ abstract public class ControllerIntegrationTest {
mockMvc = MockMvcBuilders.webAppContextSetup(context)
.addFilter(springSecurityFilterChain)
.build();
mockMvc = MockMvcBuilders.webAppContextSetup(context)
.addFilter(springSecurityFilterChain)
.apply(org.springframework.restdocs.mockmvc.MockMvcRestDocumentation
.documentationConfiguration(this.jUnitRestDocumentation)
.apply(documentationConfiguration(this.jUnitRestDocumentation)
.uris().withHost("minerva-dev.lcsb.uni.lu").withPort(80))
.apply(documentationConfiguration(this.jUnitRestDocumentation)
.operationPreprocessors()
.withResponseDefaults(Preprocessors.prettyPrint()))
.build();
executorService = Executors.newFixedThreadPool(1);
}
......
......@@ -3,14 +3,14 @@ package lcsb.mapviewer.web;
import static org.junit.Assert.*;
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.payload.PayloadDocumentation.responseFields;
import static org.springframework.restdocs.payload.PayloadDocumentation.subsectionWithPath;
import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
import static org.springframework.restdocs.request.RequestDocumentation.pathParameters;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import java.util.*;
import java.util.Arrays;
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;
......@@ -30,8 +30,6 @@ import org.springframework.transaction.annotation.Transactional;
import com.google.gson.JsonParser;
import lcsb.mapviewer.model.Project;
import lcsb.mapviewer.model.ProjectStatus;
import lcsb.mapviewer.model.graphics.MapCanvasType;
import lcsb.mapviewer.model.security.Privilege;
import lcsb.mapviewer.model.security.PrivilegeType;
import lcsb.mapviewer.model.user.User;
......@@ -53,6 +51,9 @@ public class ProjectControllerIntegrationTest extends ControllerIntegrationTest
@Autowired
private ProjectDao projectDao;
@Autowired
ProjectSnippets snippets;
private User curator;
@Before
......@@ -118,77 +119,10 @@ public class ProjectControllerIntegrationTest extends ControllerIntegrationTest
RequestBuilder request = get("/projects/{projectId}/", TEST_PROJECT)
.session(session);
List<String> projectStatuses = new ArrayList<>();
for (ProjectStatus status : ProjectStatus.values()) {
projectStatuses.add(status.name());
}
Collections.sort(projectStatuses);
List<String> mapCanvasTypes = new ArrayList<>();
for (MapCanvasType status : MapCanvasType.values()) {
mapCanvasTypes.add(status.name());
}
Collections.sort(mapCanvasTypes);
mockMvc.perform(request)
.andDo(document("projects/project_data/get_project",
pathParameters(parameterWithName("projectId").description("project identifier")),
responseFields(
fieldWithPath("projectId")
.description("project identifier")
.type("String"),
fieldWithPath("name")
.description("name")
.type("String"),
fieldWithPath("version")
.description("version")
.type("String"),
fieldWithPath("owner")
.description("login of the project creator")
.type("String"),
fieldWithPath("creationDate")
.description("when project was uploaded")
.type("String"),
subsectionWithPath("disease")
.description("identifier of the disease")
.type("MiriamAnnotation")
.optional(),
subsectionWithPath("organism")
.description("identifier of the organism")
.type("MiriamAnnotation")
.optional(),
fieldWithPath("idObject")
.ignored(),
fieldWithPath("directory")
.description(
"directory where files related to the project are located. "
+ "Whole path looks like: /minerva/map_images/{directory}")
.type("String"),
fieldWithPath("status")
.description(
"status of the uploaded project; possible values: " + StringUtils.join(projectStatuses, ", "))
.type("String"),
fieldWithPath("progress")
.description("how much current stage progressed in percent")
.type("Double"),
fieldWithPath("notifyEmail")
.description("email address connected to the project")
.type("String"),
fieldWithPath("mapCanvasType")
.description(
"type of the engine that should be used for project rendering; possible values: "
+ StringUtils.join(mapCanvasTypes, ", "))
.type("String"),
fieldWithPath("logEntries")
.description("flag indicating that there are log entries attached to the project")
.type("boolean"),
subsectionWithPath("overviewImageViews")
.description("list of overview images")
.type("Array<OverviewImage>")
.optional(),
subsectionWithPath("topOverviewImage")
.description("overview image that should be used as top level image")
.type("OverviewImage")
.optional())))
snippets.getProjectSnippet()))
.andExpect(status().is2xxSuccessful());
}
......
package lcsb.mapviewer.web;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.patch;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.delete;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.*;
import static org.springframework.restdocs.request.RequestDocumentation.*;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import java.nio.file.Files;
......@@ -23,6 +23,7 @@ import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
import org.springframework.test.web.servlet.RequestBuilder;
import lcsb.mapviewer.model.cache.UploadedFileEntry;
import lcsb.mapviewer.model.graphics.MapCanvasType;
import lcsb.mapviewer.model.user.User;
import lcsb.mapviewer.services.interfaces.IUserService;
......@@ -38,6 +39,9 @@ public class ProjectControllerIntegrationTestWithoutTransaction extends Controll
@Autowired
private IUserService userService;
@Autowired
ProjectSnippets snippets;
@Before
public void setup() {
}
......@@ -51,17 +55,78 @@ public class ProjectControllerIntegrationTestWithoutTransaction extends Controll
admin);
String body = EntityUtils.toString(new UrlEncodedFormEntity(Arrays.asList(
new BasicNameValuePair("projectId", TEST_PROJECT),
new BasicNameValuePair("name", "New Disease Map"),
new BasicNameValuePair("file-id", String.valueOf(fileEntry.getId())),
new BasicNameValuePair("mapCanvasType", "OPEN_LAYERS"),
new BasicNameValuePair("cache", "false"),
new BasicNameValuePair("description", "this is my awesome project"),
new BasicNameValuePair("notify-email", "notify.me@uni.lu"),
new BasicNameValuePair("disease", "D010300"),
new BasicNameValuePair("organism", "9606"),
new BasicNameValuePair("sbgn", "false"),
new BasicNameValuePair("semantic-zoom", "false"),
new BasicNameValuePair("version", "0.0.1"),
new BasicNameValuePair("annotate", "false"),
new BasicNameValuePair("verify-annotations", "false"),
new BasicNameValuePair("parser",
"lcsb.mapviewer.converter.model.celldesigner.CellDesignerXmlParser"))));
RequestBuilder request = post("/projects/" + TEST_PROJECT)
RequestBuilder request = post("/projects/{projectId}/", TEST_PROJECT)
.contentType(MediaType.APPLICATION_FORM_URLENCODED)
.content(body)
.session(createSession(BUILT_IN_ADMIN_LOGIN, BUILT_IN_ADMIN_PASSWORD));
mockMvc.perform(request).andExpect(status().is2xxSuccessful());
mockMvc.perform(request).andExpect(status().is2xxSuccessful())
.andDo(document("projects/project_data/create_simple",
pathParameters(parameterWithName("projectId").description("project identifier")),
requestParameters(
parameterWithName("projectId")
.description("project identifier"),
parameterWithName("file-id")
.description("identifier of the file that should be used to create project"),
parameterWithName("parser")
.description("class of the parser that should be used for parsing the file. Available options: "
+ snippets.getParsers()),
parameterWithName("cache")
.description("should the data from external sources be cached after project was created")
.optional(),
parameterWithName("description")
.description("description of the project")
.optional(),
parameterWithName("notify-email")
.description("email address that should be when something change in the project")
.optional(),
parameterWithName("disease")
.description("disease associated with the project (MESH id)")
.optional(),
parameterWithName("name")
.description("name of the project")
.optional(),
parameterWithName("organism")
.description("organism associated with the project (TAXONOMY id)")
.optional(),
parameterWithName("sbgn")
.description("should the map be visualized in sbgn-like way")
.optional(),
parameterWithName("semantic-zoom")
.description("should custom semantic zooming be enabled")
.optional(),
parameterWithName("version")
.description("version of the project")
.optional(),
parameterWithName("mapCanvasType")
.description("type of map canvas engine to be used when visualizing map. Available options: "
+ snippets.getOptionsAsString(MapCanvasType.class))
.optional(),
parameterWithName("annotate")
.description("should the project be automatically annotated")
.optional(),
parameterWithName("verify-annotations")
.description("should the annotations be verified")
.optional()),
snippets.getProjectSnippet()));
} finally {
callInSeparateThread(() -> {
......@@ -234,7 +299,7 @@ public class ProjectControllerIntegrationTestWithoutTransaction extends Controll
request = delete("/projects/" + testProject2)
.session(createSession(BUILT_IN_ADMIN_LOGIN, BUILT_IN_ADMIN_PASSWORD));
mockMvc.perform(request).andExpect(status().is2xxSuccessful());
} finally {
......
package lcsb.mapviewer.web;
import static org.springframework.restdocs.payload.PayloadDocumentation.*;
import java.util.*;
import org.apache.commons.lang3.StringUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.restdocs.payload.ResponseFieldsSnippet;
import org.springframework.stereotype.Component;
import lcsb.mapviewer.converter.Converter;
import lcsb.mapviewer.model.ProjectStatus;
import lcsb.mapviewer.model.graphics.MapCanvasType;
@Component
public class ProjectSnippets {
@Autowired
private List<Converter> converters;
public <T extends Enum<T>> String getOptionsAsString(Class<T> enumType) {
List<String> options = new ArrayList<>();
for (T c : enumType.getEnumConstants()) {
options.add(c.name());
}
Collections.sort(options);
return StringUtils.join(options, ", ");
}
public ResponseFieldsSnippet getProjectSnippet() {
return responseFields(
fieldWithPath("projectId")
.description("project identifier")
.type("String"),
fieldWithPath("name")
.description("name")
.type("String"),
fieldWithPath("version")
.description("version")
.type("String"),
fieldWithPath("owner")
.description("login of the project creator")
.type("String"),
fieldWithPath("creationDate")
.description("when project was uploaded")
.type("String"),
subsectionWithPath("disease")
.description("identifier of the disease")
.type("MiriamAnnotation")
.optional(),
subsectionWithPath("organism")
.description("identifier of the organism")
.type("MiriamAnnotation")
.optional(),
fieldWithPath("idObject")
.ignored(),
fieldWithPath("directory")
.description(
"directory where files related to the project are located. "
+ "Whole path looks like: /minerva/map_images/{directory}")
.type("String"),
fieldWithPath("status")
.description(
"status of the uploaded project; possible values: " + getOptionsAsString(ProjectStatus.class))
.type("String"),
fieldWithPath("progress")
.description("how much current stage progressed in percent")
.type("Double"),
fieldWithPath("notifyEmail")
.description("email address connected to the project")
.type("String"),
fieldWithPath("mapCanvasType")
.description(
"type of the engine that should be used for project rendering; possible values: "
+ getOptionsAsString(MapCanvasType.class))
.type("String"),
fieldWithPath("logEntries")
.description("flag indicating that there are log entries attached to the project")
.type("boolean"),
subsectionWithPath("overviewImageViews")
.description("list of overview images")
.type("Array<OverviewImage>")
.optional(),
subsectionWithPath("topOverviewImage")
.description("overview image that should be used as top level image")
.type("OverviewImage")
.optional());
}
public String getParsers() {
List<String> options = new ArrayList<>();
for (Converter c : converters) {
options.add(c.getClass().getCanonicalName());
}
Collections.sort(options);
return StringUtils.join(options, ", ");
}
}
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