documentation for file API calls

web/src/main/asciidoc/file.adoc

+= Rest API Documentation - Files
+Piotr Gawron
+v{project-version} {build-time}
+:toc: left
+:sectnums:
+
+== Create new file in the system
+=== CURL sample
+include::{snippets}/file/create_file/curl-request.adoc[]
+
+=== Request Parameters
+include::{snippets}/file/create_file/request-parameters.adoc[]
+
+=== Response Fields
+include::{snippets}/file/create_file/response-fields.adoc[]
+
+=== Sample Response
+include::{snippets}/file/create_file/response-body.adoc[]
+
+
+== Upload content of the file
+=== CURL sample
+include::{snippets}/file/upload_content/curl-request.adoc[]
+
+=== Request Parameters
+include::{snippets}/file/upload_content/request-parameters.adoc[]
+
+=== Response Fields
+include::{snippets}/file/upload_content/response-fields.adoc[]
+
+=== Sample Response
+include::{snippets}/file/upload_content/response-body.adoc[]
+
+
+== Get info about file
+=== CURL sample
+include::{snippets}/file/get_file/curl-request.adoc[]
+
+=== Path Parameters
+include::{snippets}/file/get_file/path-parameters.adoc[]
+
+=== Response Fields
+include::{snippets}/file/get_file/response-fields.adoc[]
+
+=== Sample Response
+include::{snippets}/file/get_file/response-body.adoc[]
+

web/src/test/java/lcsb/mapviewer/web/FileControllerIntegrationTest.java

 package lcsb.mapviewer.web;
 
 import static org.junit.Assert.assertNotNull;
-import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
+import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;
+import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.post;
+import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
+import static org.springframework.restdocs.payload.PayloadDocumentation.responseFields;
+import static org.springframework.restdocs.request.RequestDocumentation.*;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
 
 import java.util.Arrays;
+import java.util.List;
 
 import org.apache.http.client.entity.UrlEncodedFormEntity;
 import org.apache.http.message.BasicNameValuePair;
@@ -15,37 +21,35 @@ 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.test.annotation.Rollback;
 import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
 import org.springframework.test.web.servlet.RequestBuilder;
-import org.springframework.test.web.servlet.result.MockMvcResultHandlers;
 import org.springframework.transaction.annotation.Transactional;
 
 import com.google.gson.JsonParser;
 
 import lcsb.mapviewer.model.cache.UploadedFileEntry;
 import lcsb.mapviewer.persist.dao.cache.UploadedFileEntryDao;
+import lcsb.mapviewer.persist.dao.user.UserDao;
 
 @RunWith(SpringJUnit4ClassRunner.class)
 @Transactional
 @Rollback
 public class FileControllerIntegrationTest extends ControllerIntegrationTest {
 
-  private static final String TEST_USER_PASSWORD = "test_pass";
-
-  private static final String TEST_USER_LOGIN = "test_user";
-
   @Autowired
   private UploadedFileEntryDao uploadedFileEntryDao;
+  @Autowired
+  private UserDao userDao;
 
   @Before
   public void setup() {
-    createUser(TEST_USER_LOGIN, TEST_USER_PASSWORD);
   }
 
   @Test
   public void canCreateAndUploadFile() throws Exception {
-    MockHttpSession session = createSession(TEST_USER_LOGIN, TEST_USER_PASSWORD);
+    MockHttpSession session = createSession(BUILT_IN_TEST_ADMIN_LOGIN, BUILT_IN_TEST_ADMIN_PASSWORD);
 
     String body = EntityUtils.toString(new UrlEncodedFormEntity(Arrays.asList(
         new BasicNameValuePair("filename", "test_file"),
@@ -57,6 +61,13 @@ public class FileControllerIntegrationTest extends ControllerIntegrationTest {
         .session(session);
 
     String response = mockMvc.perform(request)
+        .andDo(document("file/create_file",
+            requestParameters(
+                parameterWithName("filename")
+                    .description("original name of the file"),
+                parameterWithName("length")
+                    .description("length of the file (in bytes)")),
+            responseFields(fileResponseFields())))
         .andExpect(status().is2xxSuccessful())
         .andReturn().getResponse().getContentAsString();
 
@@ -67,14 +78,22 @@ public class FileControllerIntegrationTest extends ControllerIntegrationTest {
         .getAsString();
 
     body = EntityUtils.toString(new UrlEncodedFormEntity(Arrays.asList(
-        new BasicNameValuePair("id", fileId),
+
         new BasicNameValuePair("data", "test_content"))));
 
-    request = post("/files/" + fileId + ":uploadContent")
+    request = post("/files/{fileId}:uploadContent", fileId)
+        .contentType(MediaType.APPLICATION_FORM_URLENCODED)
         .content(body)
         .session(session);
 
     mockMvc.perform(request)
+        .andDo(document("file/upload_content",
+            pathParameters(parameterWithName("fileId")
+                .description("file id")),
+            requestParameters(
+                parameterWithName("data")
+                    .description("content to append")),
+            responseFields(fileResponseFields())))
         .andExpect(status().is2xxSuccessful());
 
     assertNotNull(uploadedFileEntryDao.getById(Integer.valueOf(fileId)));
@@ -82,7 +101,7 @@ public class FileControllerIntegrationTest extends ControllerIntegrationTest {
 
   @Test
   public void tryToAppendToFileWithoutOwner() throws Exception {
-    MockHttpSession session = createSession(TEST_USER_LOGIN, TEST_USER_PASSWORD);
+    MockHttpSession session = createSession(BUILT_IN_TEST_ADMIN_LOGIN, BUILT_IN_TEST_ADMIN_PASSWORD);
 
     UploadedFileEntry object = new UploadedFileEntry();
     object.setFileContent(new byte[] {});
@@ -99,8 +118,43 @@ public class FileControllerIntegrationTest extends ControllerIntegrationTest {
         .content(body)
         .session(session);
 
-    mockMvc.perform(request).andDo(MockMvcResultHandlers.print())
+    mockMvc.perform(request)
         .andExpect(status().isForbidden());
   }
 
+  @Test
+  public void getInfoAboutFile() throws Exception {
+    UploadedFileEntry file = createFile("Hello world", userDao.getUserByLogin(BUILT_IN_TEST_ADMIN_LOGIN));
+    MockHttpSession session = createSession(BUILT_IN_TEST_ADMIN_LOGIN, BUILT_IN_TEST_ADMIN_PASSWORD);
+
+    RequestBuilder request = get("/files/{fileId}", file.getId() + "")
+        .session(session);
+
+    mockMvc.perform(request)
+        .andDo(document("file/get_file",
+            pathParameters(parameterWithName("fileId")
+                .description("file id")),
+            responseFields(fileResponseFields())))
+        .andExpect(status().is2xxSuccessful());
+  }
+
+  private List<FieldDescriptor> fileResponseFields() {
+    return Arrays.asList(
+        fieldWithPath("id")
+            .description("unique id in the system")
+            .type("Number"),
+        fieldWithPath("filename")
+            .description("original name of the file")
+            .type("Number"),
+        fieldWithPath("length")
+            .description("file length")
+            .type("Number"),
+        fieldWithPath("owner")
+            .description("login of the file owner")
+            .type("Number"),
+        fieldWithPath("uploadedDataLength")
+            .description("total number of uploaded bytes")
+            .type("Number"));
+  }
+
 }