Improve api docs

rpki-rtr-server/src/main/java/net/ripe/rpki/rtr/api/CacheController.java

@@ -39,6 +39,7 @@
 
 import java.util.stream.Stream;
 
+@io.swagger.annotations.Api(tags = "Cache")
 @RestController
 @RequestMapping(path = "/cache", produces = Api.API_MIME_TYPE)
 @Slf4j

rpki-rtr-server/src/main/java/net/ripe/rpki/rtr/api/ClientsController.java

@@ -41,6 +41,7 @@
 import java.util.Comparator;
 import java.util.stream.Stream;
 
+@io.swagger.annotations.Api(tags = "Clients")
 @RestController
 @RequestMapping(path = "/clients", produces = Api.API_MIME_TYPE)
 @Slf4j

rpki-rtr-server/src/main/java/net/ripe/rpki/rtr/config/SwaggerConfig.java

@@ -40,6 +40,7 @@
 import springfox.documentation.schema.AlternateTypeRule;
 import springfox.documentation.schema.AlternateTypeRules;
 import springfox.documentation.schema.WildcardType;
+import springfox.documentation.service.Tag;
 import springfox.documentation.spi.DocumentationType;
 import springfox.documentation.spring.web.plugins.Docket;
 import springfox.documentation.swagger2.annotations.EnableSwagger2;
@@ -66,8 +67,12 @@ public Docket api() {
             .directModelSubstitute(URI.class, String.class)
             .directModelSubstitute(Links.class, Object.class)
             .genericModelSubstitutes(Optional.class)
+            .tags(
+                new Tag("Cache", "Cache status"),
+                new Tag("Clients", "Client status")
+            )
             .select()
-            .apis(RequestHandlerSelectors.any())
+            .apis(RequestHandlerSelectors.basePackage("net.ripe"))
             .paths(PathSelectors.any())
             .build();
     }

rpki-validator/src/main/java/net/ripe/rpki/validator3/api/ApiError.java

@@ -30,6 +30,7 @@
 package net.ripe.rpki.validator3.api;
 
 import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Builder;
 import lombok.Value;
 import org.springframework.http.HttpStatus;
@@ -38,9 +39,12 @@
 @Builder
 @ApiModel(value = "Error")
 public class ApiError {
+    @ApiModelProperty(value = "(HTTP) status code", example = "500", required = true)
     String status;
     String code;
+    @ApiModelProperty(value = "Reason for the error", example = "Internal Server Error", required = true)
     String title;
+    @ApiModelProperty(value = "More detailed description of the error", required = false)
     String detail;
     ApiErrorSource source;
 

rpki-validator/src/main/java/net/ripe/rpki/validator3/api/ApiErrorHandler.java

@@ -58,7 +58,7 @@ public class ApiErrorHandler extends ResponseEntityExceptionHandler {
     @ExceptionHandler(value = DataRetrievalFailureException.class)
     protected ResponseEntity<ApiResponse<?>> handleDataRetrievalFailureException(DataRetrievalFailureException ex, WebRequest request) {
         HttpHeaders headers = new HttpHeaders();
-        headers.setContentType(MediaType.valueOf(Api.API_MIME_TYPE));
+        headers.setContentType(MediaType.valueOf(ValidatorApi.API_MIME_TYPE));
         return new ResponseEntity<>(ApiResponse.error(ApiError.of(HttpStatus.NOT_FOUND)), headers, HttpStatus.NOT_FOUND);
     }
 
@@ -77,7 +77,7 @@ protected ResponseEntity<Object> handleMethodArgumentNotValid(MethodArgumentNotV
                 .build()
         ).collect(Collectors.toList());
         return ResponseEntity.badRequest()
-            .contentType(MediaType.valueOf(Api.API_MIME_TYPE))
+            .contentType(MediaType.valueOf(ValidatorApi.API_MIME_TYPE))
             .body(ApiResponse.error(errors));
     }
 
@@ -102,7 +102,7 @@ protected ResponseEntity<Object> handleMethodArgumentNotValidException(MethodArg
             )
             .build();
         return ResponseEntity.badRequest()
-            .contentType(MediaType.valueOf(Api.API_MIME_TYPE))
+            .contentType(MediaType.valueOf(ValidatorApi.API_MIME_TYPE))
             .body(ApiResponse.error(error));
     }
 }

rpki-validator/src/main/java/net/ripe/rpki/validator3/api/InternalApiCall.java

@@ -0,0 +1,38 @@
+/**
+ * The BSD License
+ *
+ * Copyright (c) 2010-2018 RIPE NCC
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *   - Redistributions of source code must retain the above copyright notice,
+ *     this list of conditions and the following disclaimer.
+ *   - Redistributions in binary form must reproduce the above copyright notice,
+ *     this list of conditions and the following disclaimer in the documentation
+ *     and/or other materials provided with the distribution.
+ *   - Neither the name of the RIPE NCC nor the names of its contributors may be
+ *     used to endorse or promote products derived from this software without
+ *     specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+package net.ripe.rpki.validator3.api;
+
+import java.lang.annotation.*;
+
+@Target({ElementType.TYPE})
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+public @interface InternalApiCall {
+}

rpki-validator/src/main/java/net/ripe/rpki/validator3/api/ModelPropertyDescriptions.java

@@ -0,0 +1,63 @@
+/**
+ * The BSD License
+ *
+ * Copyright (c) 2010-2018 RIPE NCC
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *   - Redistributions of source code must retain the above copyright notice,
+ *     this list of conditions and the following disclaimer.
+ *   - Redistributions in binary form must reproduce the above copyright notice,
+ *     this list of conditions and the following disclaimer in the documentation
+ *     and/or other materials provided with the distribution.
+ *   - Neither the name of the RIPE NCC nor the names of its contributors may be
+ *     used to endorse or promote products derived from this software without
+ *     specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+package net.ripe.rpki.validator3.api;
+
+public class ModelPropertyDescriptions {
+    public static final String ASN_EXAMPLE = "3333";
+    public static final String ASN_PROPERTY = "ASN to match (without AS prefix)";
+
+    public static final String ASN_PREFIXED_PROPERTY = "ASN to match (with AS prefix)";
+    public static final String ASN_PREFIXED_EXAMPLE = "AS3333";
+
+    public static final String ASN_LIST_PROPERTY = "List of ASNs (without prefix)";
+
+    public static final String ORIGIN_PROPERTY = "Origin AS (without AS prefix)";
+    public static final String ORIGIN_PREFIXED_PROPERTY = "Origin AS (with AS prefix)";
+
+    public static final String PREFIX_EXAMPLE = "193.0.0.0/21";
+
+    /**
+     * The inputs for @see net.ripe.rpki.validator3.api.Sorting#parse
+     */
+    public static final String SORT_DIRECTION_ALLOWABLE_VALUES = "asc, desc";
+    public static final String SORT_BY_ALLOWABLE_VALUES = "prefix, asn, ta, key, location, status, validity, type, lastchecked, comment, maximumlength";
+
+    /**
+     * @see net.ripe.rpki.validator3.api.bgp.BgpPreviewService.Validity
+     */
+    public static final String VALIDITY_ALLOWABLE_VALUES = "UNKNOWN, VALID, INVALID_ASN, INVALID_LENGTH";
+
+    public static final String SOURCE_TRUST_ANCHOR = "source (name of Trust Anchor)";
+
+    public static final String TRUST_ANCHOR = "Name of trust anchor";
+    public static final String TRUST_ANCHOR_EXAMPLE = "RIPE NCC RPKI Root";
+
+    public static final String MAXLENGTH_PROPERTY = "Maxlength (>= prefix size)";
+}

rpki-validator/src/main/java/net/ripe/rpki/validator3/api/PublicApiCall.java

@@ -0,0 +1,38 @@
+/**
+ * The BSD License
+ *
+ * Copyright (c) 2010-2018 RIPE NCC
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *   - Redistributions of source code must retain the above copyright notice,
+ *     this list of conditions and the following disclaimer.
+ *   - Redistributions in binary form must reproduce the above copyright notice,
+ *     this list of conditions and the following disclaimer in the documentation
+ *     and/or other materials provided with the distribution.
+ *   - Neither the name of the RIPE NCC nor the names of its contributors may be
+ *     used to endorse or promote products derived from this software without
+ *     specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+package net.ripe.rpki.validator3.api;
+
+import java.lang.annotation.*;
+
+@Target({ElementType.TYPE})
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+public @interface PublicApiCall {
+}

rpki-validator/src/main/java/net/ripe/rpki/validator3/api/Api.java → rpki-validator/src/main/java/net/ripe/rpki/validator3/api/ValidatorApi.java

@@ -29,10 +29,10 @@
  */
 package net.ripe.rpki.validator3.api;
 
-public class Api {
+public class ValidatorApi {
     public static final String API_MIME_TYPE = "application/vnd.net.ripe.rpki.validator.v3+json; charset=UTF-8";
 
     public static final long MINIMUM_VALID_ID = 1;
 
-    private Api() {}
+    private ValidatorApi() {}
 }

rpki-validator/src/main/java/net/ripe/rpki/validator3/api/bgp/BgpPreviewController.java

@@ -29,16 +29,13 @@
  */
 package net.ripe.rpki.validator3.api.bgp;
 
+import io.swagger.annotations.*;
 import lombok.Value;
 import lombok.extern.slf4j.Slf4j;
 import net.ripe.ipresource.Asn;
 import net.ripe.ipresource.IpRange;
-import net.ripe.rpki.validator3.api.Api;
+import net.ripe.rpki.validator3.api.*;
 import net.ripe.rpki.validator3.api.ApiResponse;
-import net.ripe.rpki.validator3.api.Metadata;
-import net.ripe.rpki.validator3.api.Paging;
-import net.ripe.rpki.validator3.api.SearchTerm;
-import net.ripe.rpki.validator3.api.Sorting;
 import org.apache.commons.lang.StringUtils;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.http.ResponseEntity;
@@ -51,9 +48,15 @@
 import java.util.function.Supplier;
 import java.util.stream.Stream;
 
+import static net.ripe.rpki.validator3.api.ModelPropertyDescriptions.*;
+
+@PublicApiCall
 @RestController
-@RequestMapping(path = "/api/bgp", produces = {Api.API_MIME_TYPE, "application/json"})
+@RequestMapping(path = "/api/bgp", produces = {ValidatorApi.API_MIME_TYPE, "application/json"})
 @Slf4j
+@Api(
+        tags ="BGP preview"
+)
 public class BgpPreviewController {
 
     @Autowired
@@ -64,7 +67,9 @@ public ResponseEntity<ApiResponse<Stream<BgpPreview>>> list(
             @RequestParam(name = "startFrom", defaultValue = "0") long startFrom,
             @RequestParam(name = "pageSize", defaultValue = "20") long pageSize,
             @RequestParam(name = "search", defaultValue = "", required = false) String searchString,
+            @ApiParam(allowableValues = SORT_BY_ALLOWABLE_VALUES)
             @RequestParam(name = "sortBy", defaultValue = "prefix") String sortBy,
+            @ApiParam(allowableValues = SORT_DIRECTION_ALLOWABLE_VALUES)
             @RequestParam(name = "sortDirection", defaultValue = "asc") String sortDirection
     ) {
         final SearchTerm searchTerm = StringUtils.isNotBlank(searchString) ? new SearchTerm(searchString) : null;
@@ -108,8 +113,10 @@ private static <T> T arg(Supplier<T> s) {
 
     @Value(staticConstructor = "of")
     public static class BgpPreview {
+        @ApiModelProperty(value = ASN_PREFIXED_PROPERTY, example = ASN_PREFIXED_EXAMPLE)
         private String asn;
         private String prefix;
+        @ApiModelProperty(allowableValues = VALIDITY_ALLOWABLE_VALUES)
         private String validity;
     }
 }

rpki-validator/src/main/java/net/ripe/rpki/validator3/api/bgp/BgpPreviewService.java

@@ -31,6 +31,7 @@
 
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableSortedSet;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.extern.slf4j.Slf4j;
 import net.ripe.ipresource.Asn;
 import net.ripe.ipresource.IpRange;
@@ -74,6 +75,7 @@
 
 import static java.util.Comparator.comparing;
 import static java.util.Comparator.comparingInt;
+import static net.ripe.rpki.validator3.api.ModelPropertyDescriptions.*;
 
 @Service
 @Slf4j
@@ -109,10 +111,13 @@ public static class BgpPreviewResult {
 
     @lombok.Value(staticConstructor = "of")
     public static class ValidatingRoa {
+        @ApiModelProperty(value = ORIGIN_PROPERTY, example = ASN_EXAMPLE)
         String origin;
         String prefix;
+        @ApiModelProperty(allowableValues = VALIDITY_ALLOWABLE_VALUES)
         String validity;
         Integer maxLength;
+        @ApiModelProperty(SOURCE_TRUST_ANCHOR)
         String source;
         String uri;
         Long roaPrefixAssertionId;
@@ -121,16 +126,21 @@ public static class ValidatingRoa {
 
     @lombok.Value(staticConstructor = "of")
     public static class BgpValidity {
+        @ApiModelProperty(value = ORIGIN_PREFIXED_PROPERTY, example = ASN_PREFIXED_EXAMPLE)
         String origin;
         String prefix;
+        @ApiModelProperty(allowableValues = VALIDITY_ALLOWABLE_VALUES)
         String validity;
         List<ValidatingRoa> validatingRoas;
     }
 
     @lombok.Value(staticConstructor = "of")
     public static class BgpValidityWithFilteredResource {
+        @ApiModelProperty(value = ORIGIN_PREFIXED_PROPERTY, example = ASN_PREFIXED_EXAMPLE)
         String origin;
+        @ApiModelProperty(example = PREFIX_EXAMPLE)
         String prefix;
+        @ApiModelProperty(allowableValues = VALIDITY_ALLOWABLE_VALUES)
         String validity;
         List<ValidatingRoa> validatingRoas;
         List<ValidatingRoa> filteredRoas;

rpki-validator/src/main/java/net/ripe/rpki/validator3/api/health/HealthController.java

@@ -29,11 +29,13 @@
  */
 package net.ripe.rpki.validator3.api.health;
 
+import io.swagger.annotations.ApiOperation;
 import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.extern.slf4j.Slf4j;
-import net.ripe.rpki.validator3.api.Api;
+import net.ripe.rpki.validator3.api.ValidatorApi;
 import net.ripe.rpki.validator3.api.ApiResponse;
+import net.ripe.rpki.validator3.api.InternalApiCall;
 import net.ripe.rpki.validator3.api.bgp.BgpPreviewService;
 import net.ripe.rpki.validator3.api.bgp.BgpRisDump;
 import net.ripe.rpki.validator3.api.trustanchors.TaStatus;
@@ -52,14 +54,14 @@
 import java.time.OffsetDateTime;
 import java.time.ZoneOffset;
 import java.time.temporal.ChronoUnit;
-import java.time.temporal.TemporalUnit;
 import java.util.Collections;
 import java.util.List;
 import java.util.Map;
 import java.util.stream.Collectors;
 
+@InternalApiCall
 @RestController
-@RequestMapping(path = "/api/healthcheck", produces = {Api.API_MIME_TYPE, "application/json"})
+@RequestMapping(path = "/api/healthcheck", produces = {ValidatorApi.API_MIME_TYPE, "application/json"})
 @Slf4j
 public class HealthController {
 
@@ -78,9 +80,9 @@ public class HealthController {
     @Autowired
     private Storage storage;
 
+    @ApiOperation("Get result of validator health checks")
     @GetMapping
     public ResponseEntity<ApiResponse<?>> health() {
-
         try {
             final List<TaHealth> trustAnchorReady = storage.readTx(tx -> trustAnchors.getStatuses(tx))
                 .stream()