Adding documentation to the OxO homepage, inital commit of the doc pa…

…rt, more content necessary

oxo-web/src/main/asciidoc/api.adoc

@@ -0,0 +1,95 @@
+= OxO API guide
+
+[[overview-http-verbs]]
+== HTTP verbs
+
+This API supports the following HTTP verbs.
+
+|===
+| Verb | Usage
+
+| `GET`
+| Used to retrieve a resource
+|===
+
+[[overview-http-status-codes]]
+== HTTP status codes
+
+This API tries to adhere as closely as possible to standard HTTP and REST conventions in its
+use of HTTP status codes.
+
+|===
+| Status code | Usage
+
+| `200 OK`
+| The request completed successfully
+
+| `400 Bad Request`
+| The request was malformed. The response body will include an error providing further information
+
+| `404 Not Found`
+| The requested resource did not exist
+|===
+
+== Errors
+
+Whenever an error response (status code >= 400) is returned, the body will contain a JSON object
+that describes the problem. The error object has the following structure:
+
+include::{snippets}/error-example/response-fields.adoc[]
+
+For example, a request that attempts to apply a non-existent tag to a resource will produce a `400 Bad Request` response:
+
+include::{snippets}/error-example/http-response.adoc[]
+
+[[overview-hypermedia]]
+== Hypermedia
+
+This API uses hypermedia and resources include links to other resources in their
+responses. Responses are in http://stateless.co/hal_specification.html[Hypertext Application
+Language (HAL)] format. Links can be found benath the `_links` key. Users of the API should
+not created URIs themselves, instead they should use the above-described links to navigate
+from resource to resource.
+
+[[overview-pagination]]
+== Listing resources
+
+Requests that return multiple resources will be paginated to 20 items by default. You can change number of items
+returned using the `size` parameter up to a maximum of 500 for a single request. The API also supports the `page`
+parameter for accessing a specific page of items.
+
+=== Paging resources
+
+Links will be provided in the response to navigate the resources.
+
+==== Example request
+
+include::{snippets}/page-example/curl-request.adoc[]
+
+==== Example response
+include::{snippets}/api-example/http-response.adoc[]
+
+
+
+
+=== Datasource
+Example request
+include::{snippets}/datasources-list-example/curl-request.adoc[]
+include::{snippets}/datasources-list-example/http-request.adoc[]
+Example reply
+include::{snippets}/datasources-list-example/http-response.adoc[]
+
+
+=== mappings
+Example request
+include::{snippets}/mappings-list-example/curl-request.adoc[]
+include::{snippets}/mappings-list-example/http-request.adoc[]
+Example reply
+include::{snippets}/mappings-list-example/http-response.adoc[]
+
+=== terms
+Example request
+include::{snippets}/terms-list-example/curl-request.adoc[]
+include::{snippets}/terms-list-example/http-request.adoc[]
+Example reply
+include::{snippets}/terms-list-example/http-response.adoc[]

oxo-web/src/main/asciidoc/developer.adoc

@@ -2,10 +2,8 @@
 
 === OxO source code
 
-* You can obtain the source code at https://github.com/EBISPOT/OLS-mapping-service
+* You can obtain the source code at https://github.com/EBISPOT/OxO
 
 === OxO REST API
-* Information about the API access to our services can be found at (http://www.ebi.ac.uk/ols/docs/api)
+* Information about the API access to our services can be found at link:../docs/api[here]
 
-=== Local OxO installation
-* Details on how to build a local OLS can be found link:../docs/installation-guide[here]

oxo-web/src/main/java/uk/ac/ebi/spot/controller/ui/IndexController.java

@@ -7,6 +7,7 @@
 import org.springframework.security.core.annotation.AuthenticationPrincipal;
 import org.springframework.stereotype.Controller;
 import org.springframework.ui.Model;
+import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.RequestMapping;
 import uk.ac.ebi.spot.model.Datasource;
 import uk.ac.ebi.spot.model.Mapping;
@@ -48,10 +49,11 @@ public String home(Model model) {
         return "index";
     }
 
+    /*
     @RequestMapping(path = "docs")
     public String docs(Model model) {
         return "docs";
-    }
+    } */
 
     @RequestMapping(path = "about")
     public String about(Model model) {
@@ -80,4 +82,31 @@ public String myAccount(Model model, @AuthenticationPrincipal OrcidPrinciple pri
 
         return "myaccount";
     }
+
+
+
+
+
+    @RequestMapping({"docs"})
+    public String showDocsIndex(Model model) {
+        return "redirect:docs/index";
+    }
+    // ok, this is bad, need to find a way to deal with trailing slashes and constructing relative URLs in the thymeleaf template...
+    @RequestMapping({"docs/"})
+    public String showDocsIndex2(Model model) {
+        return "redirect:index";
+    }
+
+    @RequestMapping({"docs/{page}"})
+    public String showDocs(@PathVariable("page") String pageName, Model model) {
+        model.addAttribute("page", pageName);
+        return "docs-template";
+    }
+
+
+
+
+
+
+
 }

oxo-web/src/main/resources/static/css/oxo.css

@@ -135,4 +135,24 @@ a .ontology-source {
 
 #example_length select{
     width:60px;
+}
+
+
+/*Help Pages*/
+
+/* API doc*/
+
+.listingblock{
+    background: #ededed;
+    color: #fff;
+    text-shadow: none;
+    padding: 3%;
+    border-width: 1px;
+    border-style: dotted;
+    overflow: auto;
+}
+
+.listingblock .content .highlight{
+    white-space: pre !important;
+
 }

oxo-web/src/main/resources/templates/docs.html → oxo-web/src/main/resources/templates/docs-template.html

@@ -13,27 +13,61 @@
     <meta name="keywords" content="biosamples, europe, EBI" />
     <!- - Describe what this page is about - ->
     <meta name="description" content="EMBL-EBI" />
-
     <meta name="ebi:last-review" content="2016-12-20" />
     <!- - The last time the content was reviewed - ->
     <meta name="ebi:expiry" content="2017-12-20" />
     <!- - When this content is no longer relevant -->
 </head>
 
+<body>
+<th:block th:include="fragments/header :: header"></th:block>
 
+<section id="main-content-area" role="main">
+    <div id="content" role="main" class="row container">
 
+        <!--<div id="docs-header">
+        </div>-->
 
-<body class="level2">
+        <div id="docs-content" style="overflow: hidden;">
 
-<th:block th:include="fragments/header :: header"></th:block>
+        </div>
 
+        <!--<div id="docs-footer">
+        </div>-->
 
-<section id="main-content-area" class="row" role="main">
-    <p>Root of the REST API is <a href="api">here</a>, docs coming soon....</p>
+
+    </div>
 </section>
 
 
-    <th:block th:include="fragments/footer :: footer"></th:block>
-</body>
-</html>
+<th:block th:include="fragments/footer :: footer"></th:block>
+
+<script>
 
+$(document).ready(function() {
+
+// read the window location to set the breadcrumb
+var path = window.location.pathname;
+var pagename = path.substr(path.lastIndexOf('/') + 1);
+if (pagename == 'docs') {
+pagename = "/index";
+}
+var url_header = "../documents/".concat(pagename).concat(".html #header");
+var url_footer = "../documents/".concat(pagename).concat(".html #footer");
+var url = "../documents/".concat(pagename).concat(".html #content");
+
+$("#docs-header").load (url_header);
+$("#docs-content").load (url);
+$("#docs-footer").load (url_footer);
+
+if (pagename == 'about') {
+$('#local-nav-about').addClass('active');
+} else {
+$('#local-nav-docs').addClass('active');
+
+}
+});
+</script>
+
+</body>
+</html>

oxo-web/src/test/java/ApiDocumentation.java

@@ -5,6 +5,8 @@
 import org.junit.runner.RunWith;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.test.SpringApplicationConfiguration;
+import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
+import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
 import org.springframework.boot.test.context.SpringBootTest;
 import org.springframework.http.MediaType;
 import org.springframework.restdocs.JUnitRestDocumentation;
@@ -16,6 +18,7 @@
 import org.springframework.test.web.servlet.setup.MockMvcBuilders;
 import org.springframework.web.context.WebApplicationContext;
 import uk.ac.ebi.spot.OxoWebApp;
+import uk.ac.ebi.spot.controller.api.MappingController;
 
 import javax.servlet.RequestDispatcher;
 
@@ -42,7 +45,7 @@
 @RunWith(SpringJUnit4ClassRunner.class)
 @SpringBootTest(classes = OxoWebApp.class)
 @WebAppConfiguration
-@Ignore
+/*@Ignore*/
 public class ApiDocumentation {
 
     @Rule
@@ -57,6 +60,8 @@ public class ApiDocumentation {
 
     @Before
     public void setUp() {
+
+        System.out.print("Start the Tests");
         this.document = document("{method-name}"
                 ,
                 preprocessRequest(prettyPrint()),
@@ -65,14 +70,16 @@ public void setUp() {
 
         this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
                 .apply(documentationConfiguration(this.restDocumentation).uris()
-                                .withScheme("http")
+                                .withScheme("https")
                                 .withHost("www.ebi.ac.uk/spot/oxo")
                                 .withPort(80)
                 )
                 .alwaysDo(this.document)
                 .build();
     }
 
+
+    /*
     @Test
     public void pageExample () throws Exception {
 
@@ -97,7 +104,7 @@ public void pageExample () throws Exception {
 
         this.mockMvc.perform(get("/api/ontologies?page=1&size=1"))
                 .andExpect(status().isOk());
-    }
+    }*/
 
 
     @Test
@@ -121,6 +128,8 @@ public void errorExample() throws Exception {
         ;
     }
 
+
+    /*
     @Test
     public void apiExample () throws Exception {
 
@@ -137,7 +146,7 @@ public void apiExample () throws Exception {
         );
         this.mockMvc.perform(get("/api").accept(MediaType.APPLICATION_JSON))
                 .andExpect(status().isOk());
-    }
+    }*/
 
 
     @Test
@@ -163,6 +172,7 @@ public void datasourcesListExample () throws Exception {
     }
 
 
+    /*
     @Test
     public void mappingsExample () throws Exception {
 
@@ -192,5 +202,5 @@ public void mappingsExample () throws Exception {
 
         this.mockMvc.perform(get("/api/mappings/{mapping_id}", "efo").accept(MediaType.APPLICATION_JSON))
                 .andExpect(status().isOk());
-    }
+    }*/
 }