Commit 6315804d authored by Jean-Baptiste Nizet's avatar Jean-Baptiste Nizet
Browse files

doc: generate REST API documentation of pillar service

parent a16a0ebb
......@@ -27,7 +27,8 @@ Harvested resources which already exist are updated (they are identified by thei
Note that, to avoid letting anyone trigger a harvest, the endpoints are secured using basic authentication. The
user and the password are configured in the Spring configuration. The following snippets assume the user is
`rare`, and the password is `f01a7031fc17`.
`rare`, and the password is `f01a7031fc17`. If you don't provide the authentication information, or if it's incorrect
you'll get back a response with the status `401 Unauthorized`.
.Request
include::{snippets}/harvests/post/http-request.adoc[]
......@@ -108,3 +109,23 @@ include::{snippets}/harvests/list2/curl-request.adoc[]
.HTTPie
include::{snippets}/harvests/list2/httpie-request.adoc[]
== Pillars
=== List pillars
The pillars service is used to list pillars, their database sources, and the number of genetic resources existing for each of them in the database.
.Request
include::{snippets}/pillars/list/http-request.adoc[]
.Curl
include::{snippets}/pillars/list/curl-request.adoc[]
.HTTPie
include::{snippets}/pillars/list/httpie-request.adoc[]
.Response
include::{snippets}/pillars/list/http-response.adoc[]
.Response fields
include::{snippets}/pillars/list/response-fields.adoc[]
......@@ -93,7 +93,9 @@ class HarvesterControllerDocTest {
responseFields(
fieldWithPath("id").description("The unique ID of the harvest"),
fieldWithPath("startInstant").description("The instant when the harvest job started"),
fieldWithPath("endInstant").description("The instant when the harvest job finished. Null if it's not finished yet"),
fieldWithPath("endInstant")
.optional()
.description("The instant when the harvest job finished. Null if it's not finished yet"),
fieldWithPath("globalErrors").description("An array of global errors. Such a global error would exist, for example, for each file that can't be read"),
fieldWithPath("files").description("An array of files that have been harvested. Files that have not been harvested yet are not listed."),
fieldWithPath("files[].fileName").description("The name of the harvested file"),
......
package fr.inra.urgi.rare.pillar;
import static org.mockito.Mockito.when;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;
import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
import static org.springframework.restdocs.payload.PayloadDocumentation.responseFields;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import java.util.Arrays;
import java.util.Collections;
import fr.inra.urgi.rare.dao.GeneticResourceDao;
import fr.inra.urgi.rare.doc.DocumentationConfig;
import fr.inra.urgi.rare.search.MockBucket;
import fr.inra.urgi.rare.search.MockTermsAggregation;
import org.elasticsearch.search.aggregations.Aggregations;
import org.elasticsearch.search.aggregations.bucket.terms.Terms;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import org.springframework.context.annotation.Import;
import org.springframework.restdocs.RestDocumentationExtension;
import org.springframework.restdocs.payload.JsonFieldType;
import org.springframework.test.context.junit.jupiter.SpringExtension;
import org.springframework.test.web.servlet.MockMvc;
/**
* REST-Docs tests for {@link PillarController}
* @author JB Nizet
*/
@ExtendWith({SpringExtension.class, RestDocumentationExtension.class})
@Import(DocumentationConfig.class)
@WebMvcTest(controllers = PillarController.class, secure = false)
@AutoConfigureRestDocs
class PillarControllerDocTest {
@MockBean
private GeneticResourceDao mockGeneticResourceDao;
@Autowired
private MockMvc mockMvc;
@Test
void shouldList() throws Exception {
Terms pillarTerms = new MockTermsAggregation("pillar", Arrays.asList(
new MockBucket("Plant", 999, new Aggregations(Arrays.asList( // wrong approximate count
new MockTermsAggregation(GeneticResourceDao.DATABASE_SOURCE_AGGREGATION_NAME, Arrays.asList(
new MockBucket("Florilège", 800, new Aggregations(Arrays.asList(
new MockTermsAggregation(GeneticResourceDao.PORTAL_URL_AGGREGATION_NAME, Collections.singletonList(
new MockBucket("http://florilege.arcad-project.org/fr/collections", 800)
))
))),
new MockBucket("CNRGV", 200, new Aggregations(Arrays.asList(
new MockTermsAggregation(GeneticResourceDao.PORTAL_URL_AGGREGATION_NAME, Arrays.asList(
new MockBucket("https://cnrgv.toulouse.inra.fr/library/genomic_resource/ Aha-B-H25", 800)
))
)))
))
))),
new MockBucket("Forest", 500, new Aggregations(Arrays.asList(
new MockTermsAggregation(GeneticResourceDao.DATABASE_SOURCE_AGGREGATION_NAME, Arrays.asList(
new MockBucket("GnpIS", 500, new Aggregations(Arrays.asList(
new MockTermsAggregation(GeneticResourceDao.PORTAL_URL_AGGREGATION_NAME, Collections.emptyList()) // no URL
)))
))
)))
));
when(mockGeneticResourceDao.findPillars()).thenReturn(pillarTerms);
mockMvc.perform(get("/api/pillars"))
.andExpect(status().isOk())
.andDo(document("pillars/list",
responseFields(
fieldWithPath("[]").description("The array of pillars"),
fieldWithPath("[].name").description("The pillar name"),
fieldWithPath("[].documentCount").description("The total number of document (resources) for the pillar"),
fieldWithPath("[].databaseSources").description("The database sources of the pillar"),
fieldWithPath("[].databaseSources[].name").description("The name of the database source"),
fieldWithPath("[].databaseSources[].documentCount").description("The number of documents (resources) of the database source"),
fieldWithPath("[].databaseSources[].url")
.type(JsonFieldType.STRING)
.optional()
.description("The URL of the database source. Null if no URL was found for the database source. If several different URLs were found for the same database source (which indicates a problem in the data), then the URL of the one with the largest number of documents is used")
)));
}
}
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