From 380a49a0b795c043598d6d0a4a3bafe0e4a88d8f Mon Sep 17 00:00:00 2001
From: Lars Johansson <lars.johansson@ess.eu>
Date: Thu, 24 Feb 2022 17:14:51 +0100
Subject: [PATCH] Added REST API documentation with Springdoc and Swagger UI
---
pom.xml | 6 +
.../openepics/names/rest/api/v1/INames.java | 465 ++++++++++-----
.../names/rest/api/v1/IStructures.java | 544 +++++++++++++-----
.../controller/HealthcheckController.java | 17 +
.../controller/VerificationController.java | 11 +-
.../old/DeviceNamesControllerV0.java | 3 +
.../old/HealthcheckControllerV0.java | 3 +
.../controller/old/HistoryControllerV0.java | 3 +
.../rest/controller/old/PartControllerV0.java | 3 +
9 files changed, 787 insertions(+), 268 deletions(-)
diff --git a/pom.xml b/pom.xml
index 39a84b4..edb1b8a 100644
--- a/pom.xml
+++ b/pom.xml
@@ -66,6 +66,12 @@
<version>3.0.1</version>
</dependency>
+ <dependency>
+ <groupId>org.springdoc</groupId>
+ <artifactId>springdoc-openapi-ui</artifactId>
+ <version>1.6.6</version>
+ </dependency>
+
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
diff --git a/src/main/java/org/openepics/names/rest/api/v1/INames.java b/src/main/java/org/openepics/names/rest/api/v1/INames.java
index ff773e4..1261529 100644
--- a/src/main/java/org/openepics/names/rest/api/v1/INames.java
+++ b/src/main/java/org/openepics/names/rest/api/v1/INames.java
@@ -22,6 +22,7 @@ import java.util.List;
import org.openepics.names.rest.beans.FieldName;
import org.openepics.names.rest.beans.NameElement;
+import org.openepics.names.util.response.Response;
import org.openepics.names.util.response.ResponseBoolean;
import org.openepics.names.util.response.ResponseBooleanList;
import org.springframework.http.ResponseEntity;
@@ -32,11 +33,23 @@ import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.enums.ParameterIn;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
/**
* This part of REST API provides names data for Naming application.
*
* @author Lars Johansson
*/
+@Tag(name = "Names",
+ description = "handle names data for Naming application")
@RequestMapping("/api/v1/names")
public interface INames {
@@ -96,15 +109,37 @@ public interface INames {
* Create names by list of name elements.
* Return list of created name elements.
*
- * @param nameElements name elements
- * @return created name elements
+ * @param nameElements list of name elements
+ * @return list of created name elements
*/
- @RequestMapping (
+ @Operation(
+ summary = "Create names by array of name elements",
+ description = "Create names by array of name elements. "
+ + "Return array of created name elements."
+ + "\n\n"
+ + "Name element attributes required: \n"
+ + "- name \n"
+ + "- description \n"
+ + "- comment \n"
+ + "- either of \n"
+ + "-- subsystem \n"
+ + "-- subsystem, device type, index \n"
+ + "-- system \n"
+ + "-- system, device type, index \n"
+ + "-- system group \n"
+ + "-- system group, device type, index"
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Return array of created name elements.", content = @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = NameElement.class)))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
method = RequestMethod.POST,
produces = {"application/json"},
consumes = {"application/json"})
public List<NameElement> createNames(
- @RequestBody(required = true) List<NameElement> nameElements);
+ @Parameter(in = ParameterIn.DEFAULT, description = "array of name elements", required = true) @RequestBody(required = true) List<NameElement> nameElements);
// ----------------------------------------------------------------------------------------------------
@@ -112,196 +147,270 @@ public interface INames {
* Find valid names (search).
* Return list of name elements.
*
- * @param deleted deleted
- * @param queryFields query fields
- * @param queryValues query values
- * @param orderBy order by
- * @param isAsc is ascending
- * @param offset offset
- * @param limit limit
+ * @param deleted if deleted-only names are to be included (false for non-deleted-only names, true for deleted-only names, not used for both cases)
+ * @param queryFields search fields
+ * @param queryValues search values corresponding to search fields
+ * @param orderBy order by field
+ * @param isAsc sort order, ascending or descending
+ * @param offset offset, page starting from 0
+ * @param limit limit, page size
* @return list of name elements
*/
- @RequestMapping (
+ @Operation(
+ summary = "Find valid names (search)",
+ description = "Find valid names (search). "
+ + "Return array of name elements."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Return array of name elements.", content = @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = NameElement.class)))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
method = RequestMethod.GET,
produces = {"application/json"})
public List<NameElement> readNames(
- @RequestParam(required = false) Boolean deleted,
- @RequestParam(required = false) FieldName[] queryFields,
- @RequestParam(required = false) String[] queryValues,
- @RequestParam(required = false) FieldName orderBy,
- @RequestParam(required = false) Boolean isAsc,
- @RequestParam(required = false) Integer offset,
- @RequestParam(required = false) Integer limit);
+ @Parameter(in = ParameterIn.QUERY, description = "if deleted-only names are to be included, false for non-deleted-only names, true for deleted-only names, not used for both cases") @RequestParam(required = false) Boolean deleted,
+ @Parameter(in = ParameterIn.QUERY, description = "search fields") @RequestParam(required = false) FieldName[] queryFields,
+ @Parameter(in = ParameterIn.QUERY, description = "search values corresponding to search fields") @RequestParam(required = false) String[] queryValues,
+ @Parameter(in = ParameterIn.QUERY, description = "order by field") @RequestParam(required = false) FieldName orderBy,
+ @Parameter(in = ParameterIn.QUERY, description = "sort order, ascending or descending") @RequestParam(required = false) Boolean isAsc,
+ @Parameter(in = ParameterIn.QUERY, description = "offset, page starting from 0") @RequestParam(required = false) Integer offset,
+ @Parameter(in = ParameterIn.QUERY, description = "limit, page size") @RequestParam(required = false) Integer limit);
/**
* Find valid names by name or uuid (search).
* Return list of name elements.
*
- * @param name name or uuid
- * @param orderBy order by
- * @param isAsc is ascending
- * @param offset offset
- * @param limit limit
+ * @param name name or uuid to search for
+ * @param orderBy order by field
+ * @param isAsc sort order, ascending or descending
+ * @param offset offset, page starting from 0
+ * @param limit limit, page size
* @return list of name elements
*/
- @RequestMapping (
+ @Operation(
+ summary = "Find valid names by name or uuid (search)",
+ description = "Find valid names by name or uuid (search). "
+ + "Return array of name elements."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Return array of name elements.", content = @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = NameElement.class)))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
value = "/{name}",
method = RequestMethod.GET,
produces = {"application/json"})
public List<NameElement> readNames(
- @PathVariable("name") String name,
- @RequestParam(required = false) FieldName orderBy,
- @RequestParam(required = false) Boolean isAsc,
- @RequestParam(required = false) Integer offset,
- @RequestParam(required = false) Integer limit);
+ @Parameter(in = ParameterIn.PATH, description = "name or uuid to search for") @PathVariable("name") String name,
+ @Parameter(in = ParameterIn.QUERY, description = "order by field") @RequestParam(required = false) FieldName orderBy,
+ @Parameter(in = ParameterIn.QUERY, description = "sort order, ascending or descending") @RequestParam(required = false) Boolean isAsc,
+ @Parameter(in = ParameterIn.QUERY, description = "offset, page starting from 0") @RequestParam(required = false) Integer offset,
+ @Parameter(in = ParameterIn.QUERY, description = "limit, page size") @RequestParam(required = false) Integer limit);
/**
* Find valid names by system structure mnemonic path (search).
* Return list of name elements.
*
- * @param mnemonicpath mnemonic path
- * @param orderBy order by
- * @param isAsc is ascending
- * @param offset offset
- * @param limit limit
+ * @param mnemonicpath mnemonic path to search for
+ * @param orderBy order by field
+ * @param isAsc sort order, ascending or descending
+ * @param offset offset, page starting from 0
+ * @param limit limit, page size
* @return list of name elements
*/
- @RequestMapping (
+ @Operation(
+ summary = "Find valid names by system structure mnemonic path (search)",
+ description = "Find valid names by system structure mnemonic path (search). "
+ + "Return array of name elements."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Return array of name elements.", content = @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = NameElement.class)))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
value = "/systemstructure/{mnemonicpath}",
method = RequestMethod.GET,
produces = {"application/json"})
public List<NameElement> readNamesSystemStructure(
- @PathVariable("mnemonicpath") String mnemonicpath,
- @RequestParam(required = false) FieldName orderBy,
- @RequestParam(required = false) Boolean isAsc,
- @RequestParam(required = false) Integer offset,
- @RequestParam(required = false) Integer limit);
+ @Parameter(in = ParameterIn.PATH, description = "mnemonic path to search for") @PathVariable("mnemonicpath") String mnemonicpath,
+ @Parameter(in = ParameterIn.QUERY, description = "order by field") @RequestParam(required = false) FieldName orderBy,
+ @Parameter(in = ParameterIn.QUERY, description = "sort order, ascending or descending") @RequestParam(required = false) Boolean isAsc,
+ @Parameter(in = ParameterIn.QUERY, description = "offset, page starting from 0") @RequestParam(required = false) Integer offset,
+ @Parameter(in = ParameterIn.QUERY, description = "limit, page size") @RequestParam(required = false) Integer limit);
/**
* Find valid names by device structure mnemonic path (search).
* Return list of name elements.
*
- * @param mnemonicpath mnemonic path
- * @param orderBy order by
- * @param isAsc is ascending
- * @param offset offset
- * @param limit limit
+ * @param mnemonicpath mnemonic path to search for
+ * @param orderBy order by field
+ * @param isAsc sort order, ascending or descending
+ * @param offset offset, page starting from 0
+ * @param limit limit, page size
* @return list of name elements
*/
- @RequestMapping (
+ @Operation(
+ summary = "Find valid names by device structure mnemonic path (search)",
+ description = "Find valid names by device structure mnemonic path (search). "
+ + "Return array of name elements."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Return array of name elements.", content = @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = NameElement.class)))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
value = "/devicestructure/{mnemonicpath}",
method = RequestMethod.GET,
produces = {"application/json"})
public List<NameElement> readNamesDeviceStructure(
- @PathVariable("mnemonicpath") String mnemonicpath,
- @RequestParam(required = false) FieldName orderBy,
- @RequestParam(required = false) Boolean isAsc,
- @RequestParam(required = false) Integer offset,
- @RequestParam(required = false) Integer limit);
+ @Parameter(in = ParameterIn.PATH, description = "mnemonic path to search for") @PathVariable("mnemonicpath") String mnemonicpath,
+ @Parameter(in = ParameterIn.QUERY, description = "order by field") @RequestParam(required = false) FieldName orderBy,
+ @Parameter(in = ParameterIn.QUERY, description = "sort order, ascending or descending") @RequestParam(required = false) Boolean isAsc,
+ @Parameter(in = ParameterIn.QUERY, description = "offset, page starting from 0") @RequestParam(required = false) Integer offset,
+ @Parameter(in = ParameterIn.QUERY, description = "limit, page size") @RequestParam(required = false) Integer limit);
/**
* Find history for name by uuid (exact match).
* Return list of name elements.
*
- * @param uuid uuid
- * @param orderBy order by
- * @param isAsc is ascending
- * @param offset offset
- * @param limit limit
+ * @param uuid uuid to find history for
+ * @param orderBy order by field
+ * @param isAsc sort order, ascending or descending
+ * @param offset offset, page starting from 0
+ * @param limit limit, page size
* @return list of name elements
*/
- @RequestMapping (
+ @Operation(
+ summary = "Find history for name by uuid (exact match)",
+ description = "Find history for name by uuid (exact match). "
+ + "Return array of name elements."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Return array of name elements.", content = @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = NameElement.class)))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
value = "/history/{uuid}",
method = RequestMethod.GET,
produces = {"application/json"})
public List<NameElement> readNamesHistory(
- @PathVariable("uuid") String uuid,
- @RequestParam(required = false) FieldName orderBy,
- @RequestParam(required = false) Boolean isAsc,
- @RequestParam(required = false) Integer offset,
- @RequestParam(required = false) Integer limit);
+ @Parameter(in = ParameterIn.PATH, description = "uuid to find history for") @PathVariable("uuid") String uuid,
+ @Parameter(in = ParameterIn.QUERY, description = "order by field") @RequestParam(required = false) FieldName orderBy,
+ @Parameter(in = ParameterIn.QUERY, description = "sort order, ascending or descending") @RequestParam(required = false) Boolean isAsc,
+ @Parameter(in = ParameterIn.QUERY, description = "offset, page starting from 0") @RequestParam(required = false) Integer offset,
+ @Parameter(in = ParameterIn.QUERY, description = "limit, page size") @RequestParam(required = false) Integer limit);
// ----------------------------------------------------------------------------------------------------
/**
* Return name equivalence for name.
*
- * @param name name
+ * @param name name to get name equivalence for
* @return name equivalence
*/
- @RequestMapping (
+ @Operation(
+ summary = "Return name equivalence for name",
+ description = "Return name equivalence for name."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Return name equivalence.", content = @Content(mediaType = "text/plain", schema = @Schema(implementation = String.class))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+
+ })
+ @RequestMapping(
value = "/equivalence/{name}",
method = RequestMethod.GET)
public String equivalenceName(
- @PathVariable("name") String name);
+ @Parameter(in = ParameterIn.PATH, description = "name to get name equivalence for") @PathVariable("name") String name);
/**
* Return if name exists (exact match).
*
* <p>
- * Returned object has three fields (response, message, details).
- * <ul>
- * <li>response: boolean (true/false)</li>
- * <li>message: reason, if method fails</li>
- * <li>details: details, if method fails</li>
- * </ul>
+ * Response is true if name exists, false otherwise. Message and details are available if no response is available.
* </p>
*
- * @param name name
+ * @param name name to check if it exists
* @return if name exists
*/
- @RequestMapping (
+ @Operation(
+ summary = "Return if name exists (exact match)",
+ description = "Return if name exists (exact match)."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Response is true if name exists, false otherwise. Message and details are available if no response is available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ResponseBoolean.class))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
value = "/exists/{name}",
method = RequestMethod.GET,
produces = {"application/json"})
public ResponseEntity<ResponseBoolean> existsName(
- @PathVariable("name") String name);
+ @Parameter(in = ParameterIn.PATH, description = "name to check if it exists") @PathVariable("name") String name);
/**
- * Return if name is legacy name.
+ * Return if name is legacy name (exact match).
* A name is considered legacy name if one or more of its parents is deleted.
*
* <p>
- * Returned object has three fields (response, message, details).
- * <ul>
- * <li>response: boolean (true/false)</li>
- * <li>message: reason, if method fails</li>
- * <li>details: details, if method fails</li>
- * </ul>
+ * Response is true if name is legacy name, false otherwise. Message and details are available if no response is available.
* </p>
*
- * @param name name
+ * @param name name to check if it is legacy name
* @return if name is legacy name
*/
- @RequestMapping (
+ @Operation(
+ summary = "Return if name is legacy name (exact match)",
+ description = "Return if name is legacy name (exact match). "
+ + "A name is considered legacy name if one or more of its parents is deleted."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Response is true if name is legacy name, false otherwise. Message and details are available if no response is available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ResponseBoolean.class))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
value = "/islegacy/{name}",
method = RequestMethod.GET,
produces = {"application/json"})
public ResponseEntity<ResponseBoolean> isLegacyName(
- @PathVariable("name") String name);
+ @Parameter(in = ParameterIn.PATH, description = "name to check if it is legacy name") @PathVariable("name") String name);
/**
- * Return if name is valid to create.
+ * Return if name is valid to create (exact match).
* Method answers question 'would it be ok to create given name?'.
*
* <p>
- * Returned object has three fields (response, message, details).
- * <ul>
- * <li>response: boolean (true/false)</li>
- * <li>message: reason, if method fails</li>
- * <li>details: details, if method fails</li>
- * </ul>
+ * Response is true if name is valid to create, false otherwise. Message and details are available if no response is available.
* </p>
*
- * @param name name
+ * @param name name to check if it is valid to create
* @return if name is valid to create
*/
- @RequestMapping (
+ @Operation(
+ summary = "Return if name is valid to create (exact match)",
+ description = "Return if name is valid to create (exact match). "
+ + "Method answers question 'would it be ok to create given name?'."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Response is true if name is valid to create, false otherwise. Message and details are available if no response is available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ResponseBoolean.class))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
value = "/isvalidtocreate/{name}",
method = RequestMethod.GET,
produces = {"application/json"})
public ResponseEntity<ResponseBoolean> isValidToCreateName(
- @PathVariable("name") String name);
+ @Parameter(in = ParameterIn.PATH, description = "name to check if it is valid to create") @PathVariable("name") String name);
// ----------------------------------------------------------------------------------------------------
@@ -310,75 +419,123 @@ public interface INames {
* If names are valid to create, successful create of names can be expected.
*
* <p>
- * Returned object has four fields (message, details, response, responses).
- * <ul>
- * <li>message: reason, if method fails</li>
- * <li>details: details, if method fails</li>
- * <li>response: boolean (true/false), overall result of method</li>
- * <li>responses: list of response objects (with fields reason, details, response), one for each input element</li>
- * </ul>
+ * Response is true if all name elements validated ok, false otherwise, responses contain array with result for each name element. Message and details are available if no response is available.
* </p>
*
- * @param nameElements name elements
+ * @param nameElements list of name elements
* @return if list of name elements is valid to create
*/
- @RequestMapping (
+ @Operation(
+ summary = "Return if name elements are valid to create",
+ description = "Return if name elements are valid to create. "
+ + "If names are valid to create, successful create of names can be expected."
+ + "\n\n"
+ + "Name element attributes required: \n"
+ + "- name \n"
+ + "- description \n"
+ + "- comment \n"
+ + "- either of \n"
+ + "-- subsystem \n"
+ + "-- subsystem, device type, index \n"
+ + "-- system \n"
+ + "-- system, device type, index \n"
+ + "-- system group \n"
+ + "-- system group, device type, index"
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Response is true if all name elements validated ok, false otherwise, responses contain array with result for each name element. Message and details are available if no response is available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ResponseBooleanList.class))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
value = "/validatecreate",
method = RequestMethod.GET,
produces = {"application/json"},
consumes = {"application/json"})
public ResponseEntity<ResponseBooleanList> validateNamesCreate(
- @RequestBody(required = true) List<NameElement> nameElements);
+ @Parameter(in = ParameterIn.DEFAULT, description = "array of name elements", required = true) @RequestBody(required = true) List<NameElement> nameElements);
/**
* Return if name elements are valid to update.
* If names are valid to update, successful update of names can be expected.
*
* <p>
- * Returned object has four fields (message, details, response, responses).
- * <ul>
- * <li>message: reason, if method fails</li>
- * <li>details: details, if method fails</li>
- * <li>response: boolean (true/false), overall result of method</li>
- * <li>responses: list of response objects (with fields reason, details, response), one for each input element</li>
- * </ul>
+ * Response is true if all name elements validated ok, false otherwise, responses contain array with result for each name element. Message and details are available if no response is available.
* </p>
*
- * @param nameElements name elements
+ * @param nameElements list of name elements
* @return if list of name elements is valid to update
*/
- @RequestMapping (
+ @Operation(
+ summary = "Return if name elements are valid to update",
+ description = "Return if name elements are valid to update. "
+ + "If names are valid to update, successful update of names can be expected."
+ + "\n\n"
+ + "Name element attributes required: \n"
+ + "- name \n"
+ + "- description \n"
+ + "- comment \n"
+ + "- either of \n"
+ + "-- subsystem \n"
+ + "-- subsystem, device type, index \n"
+ + "-- system \n"
+ + "-- system, device type, index \n"
+ + "-- system group \n"
+ + "-- system group, device type, index"
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Response is true if all name elements validated ok, false otherwise, responses contain array with result for each name element. Message and details are available if no response is available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ResponseBooleanList.class))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
value = "/validateupdate",
method = RequestMethod.GET,
produces = {"application/json"},
consumes = {"application/json"})
public ResponseEntity<ResponseBooleanList> validateNamesUpdate(
- @RequestBody(required = true) List<NameElement> nameElements);
+ @Parameter(in = ParameterIn.DEFAULT, description = "array of name elements", required = true) @RequestBody(required = true) List<NameElement> nameElements);
/**
* Return if name elements are valid to delete.
* If names are valid to update, successful delete of names can be expected.
*
* <p>
- * Returned object has four fields (message, details, response, responses).
- * <ul>
- * <li>message: reason, if method fails</li>
- * <li>details: details, if method fails</li>
- * <li>response: boolean (true/false), overall result of method</li>
- * <li>responses: list of response objects (with fields reason, details, response), one for each input element</li>
- * </ul>
+ * Response is true if all name elements validated ok, false otherwise, responses contain array with result for each name element. Message and details are available if no response is available.
* </p>
*
- * @param nameElements name elements
+ * @param nameElements list of name elements
* @return if list of name elements is valid to delete
*/
- @RequestMapping (
+ @Operation(
+ summary = "Return if name elements are valid to delete",
+ description = "Return if name elements are valid to delete. "
+ + "If names are valid to update, successful delete of names can be expected."
+ + "\n\n"
+ + "Name element attributes required: \n"
+ + "- name \n"
+ + "- description \n"
+ + "- comment \n"
+ + "- either of \n"
+ + "-- subsystem \n"
+ + "-- subsystem, device type, index \n"
+ + "-- system \n"
+ + "-- system, device type, index \n"
+ + "-- system group \n"
+ + "-- system group, device type, index"
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Response is true if all name elements validated ok, false otherwise, responses contain array with result for each name element. Message and details are available if no response is available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ResponseBooleanList.class))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
value = "/validatedelete",
method = RequestMethod.GET,
produces = {"application/json"},
consumes = {"application/json"})
public ResponseEntity<ResponseBooleanList> validateNamesDelete(
- @RequestBody(required = true) List<NameElement> nameElements);
+ @Parameter(in = ParameterIn.DEFAULT, description = "array of name elements", required = true) @RequestBody(required = true) List<NameElement> nameElements);
// ----------------------------------------------------------------------------------------------------
@@ -386,16 +543,38 @@ public interface INames {
* Update names by list of name elements.
* Returns list of updated name elements.
*
- * @param nameElements name elements
- * @return updated name elements
+ * @param nameElements list of name elements
+ * @return list of updated name elements
*/
- @RequestMapping (
+ @Operation(
+ summary = "Update names by list of name elements",
+ description = "Update names by list of name elements. "
+ + "Return array of updated name elements."
+ + "\n\n"
+ + "Name element attributes required: \n"
+ + "- name \n"
+ + "- description \n"
+ + "- comment \n"
+ + "- either of \n"
+ + "-- subsystem \n"
+ + "-- subsystem, device type, index \n"
+ + "-- system \n"
+ + "-- system, device type, index \n"
+ + "-- system group \n"
+ + "-- system group, device type, index"
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Return array of updated name elements.", content = @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = NameElement.class)))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
method = RequestMethod.PUT,
produces = {"application/json"},
consumes = {"application/json"})
@PutMapping
public List<NameElement> updateNames(
- @RequestBody(required = true) List<NameElement> nameElements);
+ @Parameter(in = ParameterIn.DEFAULT, description = "array of name elements", required = true) @RequestBody(required = true) List<NameElement> nameElements);
// ----------------------------------------------------------------------------------------------------
@@ -404,13 +583,35 @@ public interface INames {
* Returns list of deleted name elements.
*
* @param uuid uuid
- * @return deleted name elements
+ * @return list of deleted name elements
*/
- @RequestMapping (
+ @Operation(
+ summary = "Delete names by list of name elements",
+ description = "Delete names by list of name elements. "
+ + "Return array of deleted name elements."
+ + "\n\n"
+ + "Name element attributes required: \n"
+ + "- name \n"
+ + "- description \n"
+ + "- comment \n"
+ + "- either of \n"
+ + "-- subsystem \n"
+ + "-- subsystem, device type, index \n"
+ + "-- system \n"
+ + "-- system, device type, index \n"
+ + "-- system group \n"
+ + "-- system group, device type, index"
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Return array of deleted name elements.", content = @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = NameElement.class)))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
method = RequestMethod.DELETE,
produces = {"application/json"},
consumes = {"application/json"})
public List<NameElement> deleteNames(
- @RequestBody(required = true) List<NameElement> nameElements);
+ @Parameter(in = ParameterIn.DEFAULT, description = "array of name elements", required = true) @RequestBody(required = true) List<NameElement> nameElements);
}
diff --git a/src/main/java/org/openepics/names/rest/api/v1/IStructures.java b/src/main/java/org/openepics/names/rest/api/v1/IStructures.java
index 6279bfb..1a480ce 100644
--- a/src/main/java/org/openepics/names/rest/api/v1/IStructures.java
+++ b/src/main/java/org/openepics/names/rest/api/v1/IStructures.java
@@ -24,6 +24,7 @@ import org.openepics.names.rest.beans.FieldStructure;
import org.openepics.names.rest.beans.Status;
import org.openepics.names.rest.beans.StructureElement;
import org.openepics.names.rest.beans.Type;
+import org.openepics.names.util.response.Response;
import org.openepics.names.util.response.ResponseBoolean;
import org.openepics.names.util.response.ResponseBooleanList;
import org.springframework.http.ResponseEntity;
@@ -34,11 +35,23 @@ import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.enums.ParameterIn;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
/**
* This part of REST API provides structures data for Naming application.
*
* @author Lars Johansson
*/
+@Tag(name = "Structures",
+ description = "handle structures data for Naming application")
@RequestMapping("/api/v1/structures")
public interface IStructures {
@@ -115,15 +128,33 @@ public interface IStructures {
* </ul>
* </p>
*
- * @param structureElements structure elements
- * @return structure elements for created structures (proposals)
+ * @param structureElements list of structure elements
+ * @return list of structure elements for created structures (proposals)
*/
- @RequestMapping (
+ @Operation(
+ summary = "Create (propose) structures by list of structure elements",
+ description = "Create (propose) structures by list of structure elements. "
+ + "Return array of created structure elements (proposals)."
+ + "\n\n"
+ + "Structure element attributes required: \n"
+ + "- type \n"
+ + "- parent (System, Subsystem, DeviceGroup, DeviceType) \n"
+ + "- name \n"
+ + "- mnemonic (System, Subsystem, Discipline, DeviceType, may be set for SystemGroup, not allowed for DeviceGroup) \n"
+ + "- description \n"
+ + "- comment"
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Return array of structure elements for created structures (proposals).", content = @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = StructureElement.class)))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
method = RequestMethod.POST,
produces = {"application/json"},
consumes = {"application/json"})
public List<StructureElement> createStructures(
- @RequestBody(required = true) List<StructureElement> structureElements);
+ @Parameter(in = ParameterIn.DEFAULT, description = "array of structure elements", required = true) @RequestBody(required = true) List<StructureElement> structureElements);
// ----------------------------------------------------------------------------------------------------
@@ -131,140 +162,199 @@ public interface IStructures {
* Find valid structures (search).
* Return list of structure elements.
*
- * @param type type
- * @param statuses statuses
- * @param deleted deleted
- * @param queryFields query fields
- * @param queryValues query values
- * @param orderBy order by
- * @param isAsc is ascending
- * @param offset offset
- * @param limit limit
+ * @param type type of structure to search in
+ * @param statuses statuses of structures to search for
+ * @param deleted if deleted-only structures are to be included (false for non-deleted-only structures, true for deleted-only structures, not used for both cases)
+ * @param queryFields search fields
+ * @param queryValues search values corresponding to search fields
+ * @param orderBy order by field
+ * @param isAsc sort order, ascending or descending
+ * @param offset offset, page starting from 0
+ * @param limit limit, page size
* @return list of structure elements
*/
- @RequestMapping (
+ @Operation(
+ summary = "Find valid structures (search)",
+ description = "Find valid structures (search). "
+ + "Return list of structure elements."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Return array of structure elements.", content = @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = StructureElement.class)))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
value = "/{type}",
method = RequestMethod.GET,
produces = {"application/json"})
@GetMapping
public List<StructureElement> readStructures(
- @PathVariable("type") Type type,
- @RequestParam(required = false) Status[] statuses,
- @RequestParam(required = false) Boolean deleted,
- @RequestParam(required = false) FieldStructure[] queryFields,
- @RequestParam(required = false) String[] queryValues,
- @RequestParam(required = false) FieldStructure orderBy,
- @RequestParam(required = false) Boolean isAsc,
- @RequestParam(required = false) Integer offset,
- @RequestParam(required = false) Integer limit);
+ @Parameter(in = ParameterIn.PATH, description = "type of structure to search in") @PathVariable("type") Type type,
+ @Parameter(in = ParameterIn.QUERY, description = "statuses of structures to search for") @RequestParam(required = false) Status[] statuses,
+ @Parameter(in = ParameterIn.QUERY, description = "if deleted-only names are to be included, false for non-deleted-only names, true for deleted-only names, not used for both cases") @RequestParam(required = false) Boolean deleted,
+ @Parameter(in = ParameterIn.QUERY, description = "search fields") @RequestParam(required = false) FieldStructure[] queryFields,
+ @Parameter(in = ParameterIn.QUERY, description = "search values corresponding to search fields") @RequestParam(required = false) String[] queryValues,
+ @Parameter(in = ParameterIn.QUERY, description = "order by field") @RequestParam(required = false) FieldStructure orderBy,
+ @Parameter(in = ParameterIn.QUERY, description = "sort order, ascending or descending") @RequestParam(required = false) Boolean isAsc,
+ @Parameter(in = ParameterIn.QUERY, description = "offset, page starting from 0") @RequestParam(required = false) Integer offset,
+ @Parameter(in = ParameterIn.QUERY, description = "limit, page size") @RequestParam(required = false) Integer limit);
/**
* Find valid children structures by type and parent uuid (exact match).
*
- * @param type type
- * @param uuid uuid
- * @param orderBy order by
- * @param isAsc is ascending
- * @param offset offset
- * @param limit limit
+ * @param type type of structure to search in
+ * @param uuid uuid to find structure for
+ * @param orderBy order by field
+ * @param isAsc sort order, ascending or descending
+ * @param offset offset, page starting from 0
+ * @param limit limit, page size
* @return list of structure elements
*/
- @RequestMapping (
+ @Operation(
+ summary = "Find valid children structures by type and parent uuid (exact match)",
+ description = "Find valid children structures by type and parent uuid (exact match)."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Return array of structure elements.", content = @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = StructureElement.class)))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
value = "/children/{type}/{uuid}",
method = RequestMethod.GET,
produces = {"application/json"})
@GetMapping
public List<StructureElement> readStructuresChildren(
- @PathVariable("type") Type type,
- @PathVariable("uuid") String uuid,
- @RequestParam(required = false) FieldStructure orderBy,
- @RequestParam(required = false) Boolean isAsc,
- @RequestParam(required = false) Integer offset,
- @RequestParam(required = false) Integer limit);
+ @Parameter(in = ParameterIn.PATH, description = "type of structure to search in") @PathVariable("type") Type type,
+ @Parameter(in = ParameterIn.PATH, description = "uuid to find structure for") @PathVariable("uuid") String uuid,
+ @Parameter(in = ParameterIn.QUERY, description = "order by field") @RequestParam(required = false) FieldStructure orderBy,
+ @Parameter(in = ParameterIn.QUERY, description = "sort order, ascending or descending") @RequestParam(required = false) Boolean isAsc,
+ @Parameter(in = ParameterIn.QUERY, description = "offset, page starting from 0") @RequestParam(required = false) Integer offset,
+ @Parameter(in = ParameterIn.QUERY, description = "limit, page size") @RequestParam(required = false) Integer limit);
/**
* Find valid structures by mnemonic (search).
* Return list of structure elements.
*
- * @param mnemonic mnemonic
- * @param orderBy order by
- * @param isAsc is ascending
- * @param offset offset
- * @param limit limit
+ * @param mnemonic mnemonic to search for
+ * @param orderBy order by field
+ * @param isAsc sort order, ascending or descending
+ * @param offset offset, page starting from 0
+ * @param limit limit, page size
* @return list of structure elements
*/
- @RequestMapping (
+ @Operation(
+ summary = "Find valid structures by mnemonic (search)",
+ description = "Find valid structures by mnemonic (search). "
+ + "Return list of structure elements."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Return array of structure elements.", content = @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = StructureElement.class)))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
value = "/mnemonic/{mnemonic}",
method = RequestMethod.GET,
produces = {"application/json"})
@GetMapping
public List<StructureElement> readStructuresMnemonic(
- @PathVariable("mnemonic") String mnemonic,
- @RequestParam(required = false) FieldStructure orderBy,
- @RequestParam(required = false) Boolean isAsc,
- @RequestParam(required = false) Integer offset,
- @RequestParam(required = false) Integer limit);
+ @Parameter(in = ParameterIn.PATH, description = "mnemonic to search for") @PathVariable("mnemonic") String mnemonic,
+ @Parameter(in = ParameterIn.QUERY, description = "order by field") @RequestParam(required = false) FieldStructure orderBy,
+ @Parameter(in = ParameterIn.QUERY, description = "sort order, ascending or descending") @RequestParam(required = false) Boolean isAsc,
+ @Parameter(in = ParameterIn.QUERY, description = "offset, page starting from 0") @RequestParam(required = false) Integer offset,
+ @Parameter(in = ParameterIn.QUERY, description = "limit, page size") @RequestParam(required = false) Integer limit);
/**
* Find valid structures by mnemonic path (search).
* Return list of structure elements.
*
- * @param mnemonicpath mnemonic path
- * @param orderBy order by
- * @param isAsc is ascending
- * @param offset offset
- * @param limit limit
+ * @param mnemonicpath mnemonic path to search for
+ * @param orderBy order by field
+ * @param isAsc sort order, ascending or descending
+ * @param offset offset, page starting from 0
+ * @param limit limit, page size
* @return list of structure elements
*/
- @RequestMapping (
+ @Operation(
+ summary = "Find valid structures by mnemonic path (search)",
+ description = "Find valid structures by mnemonic path (search). "
+ + "Return list of structure elements."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Return array of structure elements.", content = @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = StructureElement.class)))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
value = "/mnemonicpath/{mnemonicpath}",
method = RequestMethod.GET,
produces = {"application/json"})
@GetMapping
public List<StructureElement> readStructuresMnemonicpath(
- @PathVariable("mnemonicpath") String mnemonicpath,
- @RequestParam(required = false) FieldStructure orderBy,
- @RequestParam(required = false) Boolean isAsc,
- @RequestParam(required = false) Integer offset,
- @RequestParam(required = false) Integer limit);
+ @Parameter(in = ParameterIn.PATH, description = "mnemonic path to search for") @PathVariable("mnemonicpath") String mnemonicpath,
+ @Parameter(in = ParameterIn.QUERY, description = "order by field") @RequestParam(required = false) FieldStructure orderBy,
+ @Parameter(in = ParameterIn.QUERY, description = "sort order, ascending or descending") @RequestParam(required = false) Boolean isAsc,
+ @Parameter(in = ParameterIn.QUERY, description = "offset, page starting from 0") @RequestParam(required = false) Integer offset,
+ @Parameter(in = ParameterIn.QUERY, description = "limit, page size") @RequestParam(required = false) Integer limit);
/**
* Find history for structure by uuid (exact match).
* Return list of structure elements.
*
- * @param uuid uuid
- * @param type type
- * @param orderBy order by
- * @param isAsc is ascending
- * @param offset offset
- * @param limit limit
+ * @param uuid uuid to find history for
+ * @param type type of structure to search in
+ * @param orderBy order by field
+ * @param isAsc sort order, ascending or descending
+ * @param offset offset, page starting from 0
+ * @param limit limit, page size
* @return list of structure elements
*/
- @RequestMapping (
+ @Operation(
+ summary = "Find history for structure by uuid (exact match)",
+ description = "Find history for structure by uuid (exact match). "
+ + "Return list of structure elements."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Return array of structure elements.", content = @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = StructureElement.class)))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
value = "/history/{uuid}",
method = RequestMethod.GET,
produces = {"application/json"})
public List<StructureElement> readStructuresHistory(
- @PathVariable("uuid") String uuid,
- @RequestParam(required = false) Type type,
- @RequestParam(required = false) FieldStructure orderBy,
- @RequestParam(required = false) Boolean isAsc,
- @RequestParam(required = false) Integer offset,
- @RequestParam(required = false) Integer limit);
+ @Parameter(in = ParameterIn.PATH, description = "uuid to find structure for") @PathVariable("uuid") String uuid,
+ @Parameter(in = ParameterIn.QUERY, description = "type of structure to search in") @RequestParam(required = false) Type type,
+ @Parameter(in = ParameterIn.QUERY, description = "order by field") @RequestParam(required = false) FieldStructure orderBy,
+ @Parameter(in = ParameterIn.QUERY, description = "sort order, ascending or descending") @RequestParam(required = false) Boolean isAsc,
+ @Parameter(in = ParameterIn.QUERY, description = "offset, page starting from 0") @RequestParam(required = false) Integer offset,
+ @Parameter(in = ParameterIn.QUERY, description = "limit, page size") @RequestParam(required = false) Integer limit);
// ----------------------------------------------------------------------------------------------------
/**
* Return mnemonic equivalence for mnemonic.
*
- * @param mnemonic mnemonic
+ * @param mnemonic mnemonic to get mnemonic equivalence for
* @return mnemonic equivalence
*/
- @RequestMapping (
+ @Operation(
+ summary = "Return mnemonic equivalence for mnemonic",
+ description = "Return mnemonic equivalence for mnemonic."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Return mnemonic equivalence.", content = @Content(mediaType = "text/plain", schema = @Schema(implementation = String.class))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+
+ })
+ @RequestMapping(
value = "/equivalence/{mnemonic}",
method = RequestMethod.GET)
public String equivalenceMnemonic(
- @PathVariable("mnemonic") String mnemonic);
+ @Parameter(in = ParameterIn.PATH, description = "mnemonic to get mnemonic equivalence for") @PathVariable("mnemonic") String mnemonic);
/**
* Return if mnemonic exists in structure (exact match).
@@ -278,19 +368,29 @@ public interface IStructures {
* </ul>
* </p>
*
- * @param type type
- * @param mnemonic mnemonic
+ * @param type type of structure to search in
+ * @param mnemonic mnemonic to find structure for
* @return if mnemonic exists in structure
*/
- @RequestMapping (
+ @Operation(
+ summary = "Return if mnemonic exists in structure (exact match)",
+ description = "Return if mnemonic exists in structure (exact match). "
+ + "Returned object has three fields (message, details, response)."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Response is true if name exists, false otherwise. Message and details are available if no response is available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ResponseBoolean.class))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
value = "/exists/{type}/{mnemonic}",
method = RequestMethod.GET)
public ResponseEntity<ResponseBoolean> existsStructure(
- @PathVariable("type") Type type,
- @PathVariable("mnemonic") String mnemonic);
+ @Parameter(in = ParameterIn.PATH, description = "type of structure to search in") @PathVariable("type") Type type,
+ @Parameter(in = ParameterIn.PATH, description = "mnemonic to find structure for") @PathVariable("mnemonic") String mnemonic);
/**
- * Return if mnemonic path is valid to create in structure.
+ * Return if mnemonic path is valid to create in structure (exact match).
* Method answers question 'would it be ok to create given mnemonic path in structure?'.
*
* <p>
@@ -300,26 +400,32 @@ public interface IStructures {
* a device type belongs.
* </p>
*
- * <p>
- * Returned object has three fields (response, message, details).
- * <ul>
- * <li>response: boolean (true/false)</li>
- * <li>message: reason, if method fails</li>
- * <li>details: details, if method fails</li>
- * </ul>
- * </p>
- *
- * @param type type
- * @param mnemonicpath mnemonic path
+ * @param type type of structure to search in
+ * @param mnemonicpath mnemonic path to find structure for
* @return if mnemonic path is valid to create in structure
*/
- @RequestMapping (
+ @Operation(
+ summary = "Return if mnemonic path is valid to create in structure",
+ description = "Return if mnemonic path is valid to create in structure. "
+ + "Method answers question 'would it be ok to create given mnemonic path in structure?'."
+ + "\n\n"
+ + "Note that method can not fully answer question posed above. One reason is that system group "
+ + "may have empty mnemonic. Another reason is that device groups has no mnemonic and is "
+ + "between discipline and device type. Thus it can not be found which discipline (uuid-wise) "
+ + "that a device type belongs."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Response is true if structure is valid to create, false otherwise. Message and details are available if no response is available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ResponseBoolean.class))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
value = "/isvalidtocreate/{type}/{mnemonicpath}",
method = RequestMethod.GET,
produces = {"application/json"})
public ResponseEntity<ResponseBoolean> isValidToCreateStructure(
- @PathVariable("type") Type type,
- @PathVariable("mnemonicpath") String mnemonicpath);
+ @Parameter(in = ParameterIn.PATH, description = "type of structure to search in") @PathVariable("type") Type type,
+ @Parameter(in = ParameterIn.PATH, description = "mnemonic path to find structure for") @PathVariable("mnemonicpath") String mnemonicpath);
// ----------------------------------------------------------------------------------------------------
@@ -337,16 +443,34 @@ public interface IStructures {
* </ul>
* </p>
*
- * @param structureElements structure elements
+ * @param structureElements list of structure elements
* @return if list of structure elements is valid to create (propose)
*/
- @RequestMapping (
+ @Operation(
+ summary = "Return if structure elements are valid to create (propose)",
+ description = "Return if structure elements are valid to create (propose). "
+ + "If structure elements are valid to create, successful create of structures can be expected."
+ + "\n\n"
+ + "Structure element attributes required: \n"
+ + "- type \n"
+ + "- parent (System, Subsystem, DeviceGroup, DeviceType) \n"
+ + "- name \n"
+ + "- mnemonic (System, Subsystem, Discipline, DeviceType, may be set for SystemGroup, not allowed for DeviceGroup) \n"
+ + "- description \n"
+ + "- comment"
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Response is true if all structure elements validated ok, false otherwise, responses contain array with result for each structure element. Message and details are available if no response is available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ResponseBooleanList.class))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
value = "/validatecreate",
method = RequestMethod.GET,
produces = {"application/json"},
consumes = {"application/json"})
public ResponseEntity<ResponseBooleanList> validateStructuresCreate(
- @RequestBody(required = true) List<StructureElement> structureElements);
+ @Parameter(in = ParameterIn.DEFAULT, description = "array of structure elements", required = true) @RequestBody(required = true) List<StructureElement> structureElements);
/**
* Return if structure elements are valid to update (propose).
@@ -362,16 +486,34 @@ public interface IStructures {
* </ul>
* </p>
*
- * @param structureElements structure elements
+ * @param structureElements list of structure elements
* @return if list of structure elements is valid to update (propose)
*/
- @RequestMapping (
+ @Operation(
+ summary = "Return if structure elements are valid to update (propose)",
+ description = "Return if structure elements are valid to update (propose). "
+ + "If structure elements are valid to update, successful update of structures can be expected."
+ + "\n\n"
+ + "Structure element attributes required: \n"
+ + "- type \n"
+ + "- parent (System, Subsystem, DeviceGroup, DeviceType) \n"
+ + "- name \n"
+ + "- mnemonic (System, Subsystem, Discipline, DeviceType, may be set for SystemGroup, not allowed for DeviceGroup) \n"
+ + "- description \n"
+ + "- comment"
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Response is true if all structure elements validated ok, false otherwise, responses contain array with result for each structure element. Message and details are available if no response is available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ResponseBooleanList.class))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
value = "/validateupdate",
method = RequestMethod.GET,
produces = {"application/json"},
consumes = {"application/json"})
public ResponseEntity<ResponseBooleanList> validateStructuresUpdate(
- @RequestBody(required = true) List<StructureElement> structureElements);
+ @Parameter(in = ParameterIn.DEFAULT, description = "array of structure elements", required = true) @RequestBody(required = true) List<StructureElement> structureElements);
/**
* Return if structure elements are valid to delete (propose).
@@ -387,16 +529,34 @@ public interface IStructures {
* </ul>
* </p>
*
- * @param structureElements structure elements
+ * @param structureElements list of structure elements
* @return if list of structure elements is valid to delete (propose)
*/
- @RequestMapping (
+ @Operation(
+ summary = "Return if structure elements are valid to delete (propose)",
+ description = "Return if structure elements are valid to delete (propose). "
+ + "If structure elements are valid to delete, successful delete of structures can be expected."
+ + "\n\n"
+ + "Structure element attributes required: \n"
+ + "- type \n"
+ + "- parent (System, Subsystem, DeviceGroup, DeviceType) \n"
+ + "- name \n"
+ + "- mnemonic (System, Subsystem, Discipline, DeviceType, may be set for SystemGroup, not allowed for DeviceGroup) \n"
+ + "- description \n"
+ + "- comment"
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Response is true if all structure elements validated ok, false otherwise, responses contain array with result for each structure element. Message and details are available if no response is available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ResponseBooleanList.class))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
value = "/validatedelete",
method = RequestMethod.GET,
produces = {"application/json"},
consumes = {"application/json"})
public ResponseEntity<ResponseBooleanList> validateStructuresDelete(
- @RequestBody(required = true) List<StructureElement> structureElements);
+ @Parameter(in = ParameterIn.DEFAULT, description = "array of structure elements", required = true) @RequestBody(required = true) List<StructureElement> structureElements);
/**
* Return if structure elements are valid to approve.
@@ -412,16 +572,34 @@ public interface IStructures {
* </ul>
* </p>
*
- * @param structureElements structure elements
+ * @param structureElements list of structure elements
* @return if list of structure elements is valid to approve
*/
- @RequestMapping (
+ @Operation(
+ summary = "Return if structure elements are valid to approve",
+ description = "Return if structure elements are valid to approve. "
+ + "If structure elements are valid to approve, successful approve of structures can be expected."
+ + "\n\n"
+ + "Structure element attributes required: \n"
+ + "- type \n"
+ + "- parent (System, Subsystem, DeviceGroup, DeviceType) \n"
+ + "- name \n"
+ + "- mnemonic (System, Subsystem, Discipline, DeviceType, may be set for SystemGroup, not allowed for DeviceGroup) \n"
+ + "- description \n"
+ + "- comment"
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Response is true if all structure elements validated ok, false otherwise, responses contain array with result for each structure element. Message and details are available if no response is available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ResponseBooleanList.class))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
value = "/validateapprove",
method = RequestMethod.GET,
produces = {"application/json"},
consumes = {"application/json"})
public ResponseEntity<ResponseBooleanList> validateStructuresApprove(
- @RequestBody(required = true) List<StructureElement> structureElements);
+ @Parameter(in = ParameterIn.DEFAULT, description = "array of structure elements", required = true) @RequestBody(required = true) List<StructureElement> structureElements);
/**
* Return if structure elements are valid to cancel.
@@ -437,16 +615,34 @@ public interface IStructures {
* </ul>
* </p>
*
- * @param structureElements structure elements
+ * @param structureElements list of structure elements
* @return if list of structure elements is valid to cancel
*/
- @RequestMapping (
+ @Operation(
+ summary = "Return if structure elements are valid to cancel",
+ description = "Return if structure elements are valid to cancel. "
+ + "If structure elements are valid to cancel, successful cancel of structures can be expected."
+ + "\n\n"
+ + "Structure element attributes required: \n"
+ + "- type \n"
+ + "- parent (System, Subsystem, DeviceGroup, DeviceType) \n"
+ + "- name \n"
+ + "- mnemonic (System, Subsystem, Discipline, DeviceType, may be set for SystemGroup, not allowed for DeviceGroup) \n"
+ + "- description \n"
+ + "- comment"
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Response is true if all structure elements validated ok, false otherwise, responses contain array with result for each structure element. Message and details are available if no response is available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ResponseBooleanList.class))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
value = "/validatecancel",
method = RequestMethod.GET,
produces = {"application/json"},
consumes = {"application/json"})
public ResponseEntity<ResponseBooleanList> validateStructuresCancel(
- @RequestBody(required = true) List<StructureElement> structureElements);
+ @Parameter(in = ParameterIn.DEFAULT, description = "array of structure elements", required = true) @RequestBody(required = true) List<StructureElement> structureElements);
/**
* Return if structure elements are valid to reject.
@@ -462,16 +658,34 @@ public interface IStructures {
* </ul>
* </p>
*
- * @param structureElements structure elements
+ * @param structureElements list of structure elements
* @return if list of structure elements is valid to reject
*/
- @RequestMapping (
+ @Operation(
+ summary = "Return if structure elements are valid to reject",
+ description = "Return if structure elements are valid to reject. "
+ + "If structure elements are valid to reject, successful reject of structures can be expected."
+ + "\n\n"
+ + "Structure element attributes required: \n"
+ + "- type \n"
+ + "- parent (System, Subsystem, DeviceGroup, DeviceType) \n"
+ + "- name \n"
+ + "- mnemonic (System, Subsystem, Discipline, DeviceType, may be set for SystemGroup, not allowed for DeviceGroup) \n"
+ + "- description \n"
+ + "- comment"
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Response is true if all structure elements validated ok, false otherwise, responses contain array with result for each structure element. Message and details are available if no response is available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ResponseBooleanList.class))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
value = "/validatereject",
method = RequestMethod.GET,
produces = {"application/json"},
consumes = {"application/json"})
public ResponseEntity<ResponseBooleanList> validateStructuresReject(
- @RequestBody(required = true) List<StructureElement> structureElements);
+ @Parameter(in = ParameterIn.DEFAULT, description = "array of structure elements", required = true) @RequestBody(required = true) List<StructureElement> structureElements);
// ----------------------------------------------------------------------------------------------------
@@ -479,15 +693,33 @@ public interface IStructures {
* Update (propose) structures by list of structure elements.
* Return list of updated structure elements (proposals).
*
- * @param structureElements structure elements
- * @return structure elements for updated structures (proposals)
+ * @param structureElements list of structure elements
+ * @return list of structure elements for updated structures (proposals)
*/
- @RequestMapping (
+ @Operation(
+ summary = "Update (propose) structures by list of structure elements",
+ description = "Update (propose) structures by list of structure elements. "
+ + "Return array of updated structure elements (proposals)."
+ + "\n\n"
+ + "Structure element attributes required: \n"
+ + "- type \n"
+ + "- parent (System, Subsystem, DeviceGroup, DeviceType) \n"
+ + "- name \n"
+ + "- mnemonic (System, Subsystem, Discipline, DeviceType, may be set for SystemGroup, not allowed for DeviceGroup) \n"
+ + "- description \n"
+ + "- comment"
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Return array of structure elements for updated structures (proposals).", content = @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = StructureElement.class)))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
method = RequestMethod.PUT,
produces = {"application/json"},
consumes = {"application/json"})
public List<StructureElement> updateStructures(
- @RequestBody(required = true) List<StructureElement> structureElements);
+ @Parameter(in = ParameterIn.DEFAULT, description = "array of structure elements", required = true) @RequestBody(required = true) List<StructureElement> structureElements);
// ----------------------------------------------------------------------------------------------------
@@ -495,15 +727,33 @@ public interface IStructures {
* Delete (propose) structures by list of structure elements.
* Return list of deleted structure elements (proposals).
*
- * @param structureElements structure elements
- * @return structure elements for deleted structures (proposals)
+ * @param structureElements list of structure elements
+ * @return list of structure elements for deleted structures (proposals)
*/
- @RequestMapping (
+ @Operation(
+ summary = "Delete (propose) structures by list of structure elements",
+ description = "Delete (propose) structures by list of structure elements. "
+ + "Return array of deleted structure elements (proposals)."
+ + "\n\n"
+ + "Structure element attributes required: \n"
+ + "- type \n"
+ + "- parent (System, Subsystem, DeviceGroup, DeviceType) \n"
+ + "- name \n"
+ + "- mnemonic (System, Subsystem, Discipline, DeviceType, may be set for SystemGroup, not allowed for DeviceGroup) \n"
+ + "- description \n"
+ + "- comment"
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Return array of structure elements for deleted structures (proposals).", content = @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = StructureElement.class)))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
method = RequestMethod.DELETE,
produces = {"application/json"},
consumes = {"application/json"})
public List<StructureElement> deleteStructures(
- @RequestBody(required = true) List<StructureElement> structureElements);
+ @Parameter(in = ParameterIn.DEFAULT, description = "array of structure elements", required = true) @RequestBody(required = true) List<StructureElement> structureElements);
// ----------------------------------------------------------------------------------------------------
@@ -511,45 +761,75 @@ public interface IStructures {
* Approve structures (proposals) by list of structure elements.
* Return list of approved structure elements.
*
- * @param structureElements structure elements
- * @return structure elements for approved structures
+ * @param structureElements list of structure elements
+ * @return list of structure elements for approved structures
*/
- @RequestMapping (
+ @Operation(
+ summary = "Approve structures (proposals) by list of structure elements",
+ description = "Approve structures (proposals) by list of structure elements. "
+ + "Return list of approved structure elements."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Return array of structure elements for approved structures.", content = @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = StructureElement.class)))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
value = "/approve",
method = RequestMethod.PATCH,
produces = {"application/json"},
consumes = {"application/json"})
public List<StructureElement> approveStructures(
- @RequestBody(required = true) List<StructureElement> structureElements);
+ @Parameter(in = ParameterIn.DEFAULT, description = "array of structure elements", required = true) @RequestBody(required = true) List<StructureElement> structureElements);
/**
* Cancel structures (proposals) by list of structure elements.
* Return list of cancelled structure elements.
*
- * @param structureElements structure elements
- * @return structure elements for cancelled structures
+ * @param structureElements list of structure elements
+ * @return list of structure elements for cancelled structures
*/
- @RequestMapping (
+ @Operation(
+ summary = "Cancel structures (proposals) by list of structure elements",
+ description = "Cancel structures (proposals) by list of structure elements. "
+ + "Return list of cancelled structure elements."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Return array of structure elements for cancelled structures.", content = @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = StructureElement.class)))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
value = "/cancel",
method = RequestMethod.PATCH,
produces = {"application/json"},
consumes = {"application/json"})
public List<StructureElement> cancelStructures(
- @RequestBody(required = true) List<StructureElement> structureElements);
+ @Parameter(in = ParameterIn.DEFAULT, description = "array of structure elements", required = true) @RequestBody(required = true) List<StructureElement> structureElements);
/**
* Reject structures (proposals) by list of structure elements.
* Return list of rejected structure elements.
*
- * @param structureElements structure elements
- * @return structure elements for rejected structures
+ * @param structureElements list of structure elements
+ * @return list of structure elements for rejected structures
*/
- @RequestMapping (
+ @Operation(
+ summary = "Reject structures (proposals) by list of structure elements",
+ description = "Reject structures (proposals) by list of structure elements. "
+ + "Return list of rejected structure elements."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Return array of structure elements for rejected structures.", content = @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = StructureElement.class)))),
+ @ApiResponse(responseCode = "400", description = "Bad request. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
+ @ApiResponse(responseCode = "500", description = "Internal server error. Message and details are available.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class)))
+ })
+ @RequestMapping(
value = "/reject",
method = RequestMethod.PATCH,
produces = {"application/json"},
consumes = {"application/json"})
public List<StructureElement> rejectStructures(
- @RequestBody(required = true) List<StructureElement> structureElements);
+ @Parameter(in = ParameterIn.DEFAULT, description = "array of structure elements", required = true) @RequestBody(required = true) List<StructureElement> structureElements);
}
diff --git a/src/main/java/org/openepics/names/rest/controller/HealthcheckController.java b/src/main/java/org/openepics/names/rest/controller/HealthcheckController.java
index d34ab94..84bf8aa 100644
--- a/src/main/java/org/openepics/names/rest/controller/HealthcheckController.java
+++ b/src/main/java/org/openepics/names/rest/controller/HealthcheckController.java
@@ -27,11 +27,20 @@ import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
/**
* This part of REST API provides healthcheck for Naming application.
*
* @author Lars Johansson
*/
+@Tag(name = "Healthcheck",
+ description = "perform healthcheck for Naming application")
@RestController
@RequestMapping("/healthcheck")
@EnableAutoConfiguration
@@ -51,6 +60,14 @@ public class HealthcheckController {
*
* @return server timestamp
*/
+ @Operation(
+ summary = "Perform healthcheck for Naming application in general and healtcheck endpoint in particular",
+ description = "Perform healthcheck for Naming application in general and healtcheck endpoint in particular. "
+ + "To be used mainly for checking HTTP response code, in particular HTTP STATUS OK - 200."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(responseCode = "200", description = "Method completed OK. Return healthcheck as server timestamp.", content = @Content(mediaType = "text/plain", schema = @Schema(implementation = String.class)))
+ })
@GetMapping
public String readHealthcheck() {
// return healthcheck as server timestamp
diff --git a/src/main/java/org/openepics/names/rest/controller/VerificationController.java b/src/main/java/org/openepics/names/rest/controller/VerificationController.java
index 1e0f691..efca0fe 100644
--- a/src/main/java/org/openepics/names/rest/controller/VerificationController.java
+++ b/src/main/java/org/openepics/names/rest/controller/VerificationController.java
@@ -59,6 +59,8 @@ import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
+import io.swagger.v3.oas.annotations.Hidden;
+
/**
* This part of REST API provides verification of data migration for Naming application.
*
@@ -74,6 +76,7 @@ import org.springframework.web.bind.annotation.RestController;
*
* @author Lars Johansson
*/
+@Hidden
@RestController
@RequestMapping("/verification")
@EnableAutoConfiguration
@@ -128,7 +131,7 @@ public class VerificationController {
*
* @return report of data migration
*/
- @GetMapping ("/migration_devicerevision")
+ @GetMapping("/migration_devicerevision")
public String readMigrationDeviceRevision() {
// verification of
// name vs. devicerevision, device
@@ -310,7 +313,7 @@ public class VerificationController {
*
* @return report of data migration
*/
- @GetMapping ("/migration_namepartrevision")
+ @GetMapping("/migration_namepartrevision")
public String readMigrationNamePartRevision() {
// verification of
// systemgroup
@@ -785,7 +788,7 @@ public class VerificationController {
*
* @return report of reachability of data
*/
- @GetMapping ("/data_reachable")
+ @GetMapping("/data_reachable")
public String readDataReachable() {
StringBuilder reportHtml = new StringBuilder();
@@ -921,7 +924,7 @@ public class VerificationController {
*
* @return
*/
- @GetMapping ("/restapi_oldvsnew")
+ @GetMapping("/restapi_oldvsnew")
public String readRestApiOldVsNew() {
StringBuilder reportHtml = new StringBuilder();
diff --git a/src/main/java/org/openepics/names/rest/controller/old/DeviceNamesControllerV0.java b/src/main/java/org/openepics/names/rest/controller/old/DeviceNamesControllerV0.java
index e1bfa17..d749532 100644
--- a/src/main/java/org/openepics/names/rest/controller/old/DeviceNamesControllerV0.java
+++ b/src/main/java/org/openepics/names/rest/controller/old/DeviceNamesControllerV0.java
@@ -26,6 +26,8 @@ import java.util.logging.Logger;
import java.util.regex.Pattern;
import java.util.regex.PatternSyntaxException;
+import io.swagger.v3.oas.annotations.Hidden;
+
import org.apache.commons.lang3.StringUtils;
import org.openepics.names.repository.IDeviceGroupRepository;
import org.openepics.names.repository.IDeviceTypeRepository;
@@ -54,6 +56,7 @@ import com.google.common.collect.Lists;
*
* @author Lars Johansson
*/
+@Hidden
@RestController
@RequestMapping("/rest/deviceNames")
@EnableAutoConfiguration
diff --git a/src/main/java/org/openepics/names/rest/controller/old/HealthcheckControllerV0.java b/src/main/java/org/openepics/names/rest/controller/old/HealthcheckControllerV0.java
index 94606e6..e341447 100644
--- a/src/main/java/org/openepics/names/rest/controller/old/HealthcheckControllerV0.java
+++ b/src/main/java/org/openepics/names/rest/controller/old/HealthcheckControllerV0.java
@@ -27,11 +27,14 @@ import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
+import io.swagger.v3.oas.annotations.Hidden;
+
/**
* This part of REST API provides healthcheck of Naming application.
*
* @author Lars Johansson
*/
+@Hidden
@RestController
@RequestMapping("/rest/healthcheck")
@EnableAutoConfiguration
diff --git a/src/main/java/org/openepics/names/rest/controller/old/HistoryControllerV0.java b/src/main/java/org/openepics/names/rest/controller/old/HistoryControllerV0.java
index 9ec01d7..99cf133 100644
--- a/src/main/java/org/openepics/names/rest/controller/old/HistoryControllerV0.java
+++ b/src/main/java/org/openepics/names/rest/controller/old/HistoryControllerV0.java
@@ -49,11 +49,14 @@ import org.springframework.web.bind.annotation.RestController;
import com.google.common.collect.Lists;
+import io.swagger.v3.oas.annotations.Hidden;
+
/**
* This part of REST API provides history for names and name part data for Naming application.
*
* @author Lars Johansson
*/
+@Hidden
@RestController
@RequestMapping("/rest/history")
@EnableAutoConfiguration
diff --git a/src/main/java/org/openepics/names/rest/controller/old/PartControllerV0.java b/src/main/java/org/openepics/names/rest/controller/old/PartControllerV0.java
index c354d1b..70f8fb9 100644
--- a/src/main/java/org/openepics/names/rest/controller/old/PartControllerV0.java
+++ b/src/main/java/org/openepics/names/rest/controller/old/PartControllerV0.java
@@ -51,11 +51,14 @@ import org.springframework.web.bind.annotation.RestController;
import com.google.common.collect.Lists;
+import io.swagger.v3.oas.annotations.Hidden;
+
/**
* This part of REST API provides name part data for Naming application.
*
* @author Lars Johansson
*/
+@Hidden
@RestController
@RequestMapping("/rest/parts")
@EnableAutoConfiguration
--
GitLab