doc: improve API documentation (descriptions, summary, examples) (#567)

folio-org · Apr 18, 2024 · 056d3b8 · 056d3b8
1 parent d6aeb93
commit 056d3b8
Show file tree

Hide file tree

Showing 133 changed files with 1,993 additions and 526 deletions.
diff --git a/.github/workflows/spectral-lint.yml b/.github/workflows/spectral-lint.yml
@@ -0,0 +1,17 @@
+name: Run Spectral on Pull Requests
+
+on:
+  - pull_request
+
+jobs:
+  build:
+    name: Run Spectral
+    runs-on: ubuntu-latest
+    steps:
+      # Check out the repository
+      - uses: actions/checkout@v3
+
+      # Run Spectral
+      - uses: stoplightio/spectral-action@latest
+        with:
+          file_glob: 'src/main/resources/swagger.api/*.yaml'
diff --git a/.spectral.yaml b/.spectral.yaml
@@ -0,0 +1,157 @@
+extends: [ "spectral:oas" ]
+aliases:
+  PathItem:
+    description: ''
+    targets:
+      - formats:
+          - oas2
+        given:
+          - "$.paths[*]"
+      - formats:
+          - oas3
+        given:
+          - "$.paths[*]"
+  OperationObject:
+    description: 'The complete operation object. Use it in combo with field object.'
+    targets:
+      - formats:
+          - oas2
+        given:
+          - "#PathItem[get,put,post,delete,options,head,patch,trace]"
+      - formats:
+          - oas3
+        given:
+          - "#PathItem[get,put,post,delete,options,head,patch,trace]"
+  DescribableObjects:
+    description: ''
+    targets:
+      - formats:
+          - oas2
+        given:
+          - "$.info"
+          - "$.tags[*]"
+          - "#OperationObject"
+          - "$.paths[*][*].responses[*]"
+          - "$..parameters[?(@ && @.in)]"
+          - "$.definitions[*]"
+      - formats:
+          - oas3
+        given:
+          - "$.info"
+          - "$.tags[*]"
+          - "#OperationObject"
+          - "$.paths[*][*].responses[*]"
+          - "$..parameters[?(@ && @.in)]"
+          - "$.components.schemas[*]"
+          - "$.servers[*]"
+  MediaTypeObjects:
+    description: ''
+    targets:
+      - formats:
+          - oas2
+        given:
+          - $.paths[*][*]..parameters[?(@ && @.in == "body")]
+          - "$.paths[*][*].responses[*]"
+      - formats:
+          - oas3
+        given:
+          - "$.paths[*][*].requestBody.content[*]"
+          - "$.paths[*][*].responses[*].content[*]"
+rules:
+  docs-descriptions:
+    given:
+      - "#DescribableObjects"
+    severity: warn
+    then:
+      - function: truthy
+        field: description
+      - function: length
+        functionOptions:
+          min: 10
+        field: description
+      - function: pattern
+        functionOptions:
+          match: "/^[A-Z]/"
+        field: description
+    description: "Descriptions should be provided for describable objects, such as `info`, `tags`, `operations`, `parameters`, and more."
+    message: "{{error}}."
+  docs-info-contact:
+    given:
+      - "$"
+    severity: warn
+    then:
+      function: truthy
+      field: info.contact
+    description: "`Info` object should include contact information."
+  docs-parameters-examples-or-schema:
+    given:
+      - "$.paths.parameters[*]"
+    severity: info
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          anyOf:
+            - required:
+                - examples
+            - required:
+                - schema
+    description: "Path parameter must contain a defined schema or examples."
+    message: No example or schema provided for {{property}}
+    formats:
+      - oas3
+  docs-summary:
+    given:
+      - "#PathItem[*]"
+    severity: error
+    then:
+      - function: truthy
+        field: summary
+    description: "Path parameter must contain a defined schema or examples."
+    message: No summary provided for {{property}}
+    formats:
+      - oas3
+  docs-media-types-examples-or-schema:
+    given:
+      - "#MediaTypeObjects"
+    severity: info
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          anyOf:
+            - required:
+                - examples
+            - required:
+                - schema
+    description: "Media object must contain a defined schema or examples."
+    message: No example or schema provided for {{property}}
+    formats:
+      - oas3
+  docs-tags-alphabetical:
+    given:
+      - "$"
+    severity: warn
+    then:
+      function: alphabetical
+      functionOptions:
+        keyedBy: name
+      field: tags
+    description: "Tags are not in alphabetical order."
+    message: Tags should be defined in alphabetical order
+  docs-operation-tags:
+    given:
+      - "#OperationObject"
+    severity: warn
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: array
+          minItems: 1
+      field: tags
+    description: "Operation must have at least one tag."
+    message: Operation should have non-empty `tags` array.
+
diff --git a/src/main/java/org/folio/search/controller/BrowseController.java b/src/main/java/org/folio/search/controller/BrowseController.java
@@ -53,10 +53,9 @@ public class BrowseController implements BrowseApi {
   private final TenantProvider tenantProvider;
 
   @Override
-  public ResponseEntity<AuthorityBrowseResult> browseAuthorities(String query, String tenant,
-                                                                 Integer limit, Boolean expandAll,
-                                                                 Boolean highlightMatch,
-                                                                 Integer precedingRecordsCount) {
+  public ResponseEntity<AuthorityBrowseResult> browseAuthorities(String query, String tenant, Boolean expandAll,
+                                                                 Boolean highlightMatch, Integer precedingRecordsCount,
+                                                                 Integer limit) {
     var browseRequest = getBrowseRequestBuilder(query, tenant, limit, expandAll, highlightMatch, precedingRecordsCount)
       .resource(AUTHORITY_RESOURCE).targetField(AUTHORITY_BROWSING_FIELD).build();
     var browseResult = authorityBrowseService.browse(browseRequest);
@@ -90,10 +89,10 @@ public ResponseEntity<CallNumberBrowseResult> browseInstancesByCallNumber(String
 
   @Override
   public ResponseEntity<ClassificationNumberBrowseResult> browseInstancesByClassificationNumber(
-    BrowseOptionType browseOptionId, String query, String tenant, Integer limit, Boolean expandAll,
+    BrowseOptionType browseOptionId, String query, String tenant, Integer limit,
     Boolean highlightMatch, Integer precedingRecordsCount) {
 
-    var browseRequest = getBrowseRequestBuilder(query, tenant, limit, expandAll, highlightMatch, precedingRecordsCount)
+    var browseRequest = getBrowseRequestBuilder(query, tenant, limit, false, highlightMatch, precedingRecordsCount)
       .resource(INSTANCE_CLASSIFICATION_RESOURCE)
       .browseOptionType(browseOptionId)
       .targetField(CLASSIFICATION_NUMBER_BROWSING_FIELD)

diff --git a/src/main/java/org/folio/search/controller/SearchController.java b/src/main/java/org/folio/search/controller/SearchController.java
@@ -24,19 +24,9 @@ public class SearchController implements SearchApi {
   private final TenantProvider tenantProvider;
 
   @Override
-  public ResponseEntity<InstanceSearchResult> searchInstances(String tenantId, String query, Integer limit,
-                                                              Integer offset, Boolean expandAll) {
-    tenantId = tenantProvider.getTenant(tenantId);
-    var searchRequest = CqlSearchRequest.of(Instance.class, tenantId, query, limit, offset, expandAll);
-    var result = searchService.search(searchRequest);
-    return ResponseEntity.ok(new InstanceSearchResult()
-      .instances(result.getRecords())
-      .totalRecords(result.getTotalRecords()));
-  }
-
-  @Override
-  public ResponseEntity<AuthoritySearchResult> searchAuthorities(
-    String tenant, String query, Integer limit, Integer offset, Boolean expandAll, Boolean includeNumberOfTitles) {
+  public ResponseEntity<AuthoritySearchResult> searchAuthorities(String tenant, String query, Integer limit,
+                                                                 Integer offset, Boolean expandAll,
+                                                                 Boolean includeNumberOfTitles) {
 
     tenant = tenantProvider.getTenant(tenant);
     var searchRequest = CqlSearchRequest.of(
@@ -46,4 +36,15 @@ public ResponseEntity<AuthoritySearchResult> searchAuthorities(
       .authorities(result.getRecords())
       .totalRecords(result.getTotalRecords()));
   }
+
+  @Override
+  public ResponseEntity<InstanceSearchResult> searchInstances(String tenantId, String query, Integer limit,
+                                                              Integer offset, Boolean expandAll) {
+    tenantId = tenantProvider.getTenant(tenantId);
+    var searchRequest = CqlSearchRequest.of(Instance.class, tenantId, query, limit, offset, expandAll);
+    var result = searchService.search(searchRequest);
+    return ResponseEntity.ok(new InstanceSearchResult()
+      .instances(result.getRecords())
+      .totalRecords(result.getTotalRecords()));
+  }
 }
diff --git a/src/main/java/org/folio/search/service/setter/AbstractIdentifierProcessor.java b/src/main/java/org/folio/search/service/setter/AbstractIdentifierProcessor.java
@@ -11,7 +11,7 @@
 import lombok.Getter;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.log4j.Log4j2;
-import org.folio.search.domain.dto.Identifiers;
+import org.folio.search.domain.dto.Identifier;
 import org.folio.search.integration.ReferenceDataService;
 import org.folio.search.model.client.CqlQueryParam;
 
@@ -29,12 +29,12 @@ public abstract class AbstractIdentifierProcessor<T> implements FieldProcessor<T
    * @param identifiers event body as map to process
    * @return {@link Set} of filtered identifiers value
    */
-  protected Set<String> filterIdentifiersValue(List<Identifiers> identifiers) {
+  protected Set<String> filterIdentifiersValue(List<Identifier> identifiers) {
     var identifierTypeIds = fetchIdentifierIdsFromCache();
 
     return toStreamSafe(identifiers)
       .filter(identifier -> identifierTypeIds.contains(identifier.getIdentifierTypeId()))
-      .map(Identifiers::getValue)
+      .map(Identifier::getValue)
       .filter(Objects::nonNull)
       .map(String::trim)
       .collect(toCollection(LinkedHashSet::new));

diff --git a/src/main/java/org/folio/search/service/setter/AbstractLccnProcessor.java b/src/main/java/org/folio/search/service/setter/AbstractLccnProcessor.java
@@ -9,7 +9,7 @@
 import java.util.Set;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
-import org.folio.search.domain.dto.Identifiers;
+import org.folio.search.domain.dto.Identifier;
 import org.folio.search.integration.ReferenceDataService;
 
 public abstract class AbstractLccnProcessor<T> extends AbstractIdentifierProcessor<T> {
@@ -28,5 +28,5 @@ public Set<String> getFieldValue(T entity) {
       .collect(Collectors.toCollection(LinkedHashSet::new));
   }
 
-  protected abstract List<Identifiers> getIdentifiers(T entity);
+  protected abstract List<Identifier> getIdentifiers(T entity);
 }
diff --git a/src/main/java/org/folio/search/service/setter/authority/LccnAuthorityProcessor.java b/src/main/java/org/folio/search/service/setter/authority/LccnAuthorityProcessor.java
@@ -4,7 +4,7 @@
 import java.util.List;
 import java.util.Optional;
 import org.folio.search.domain.dto.Authority;
-import org.folio.search.domain.dto.Identifiers;
+import org.folio.search.domain.dto.Identifier;
 import org.folio.search.integration.ReferenceDataService;
 import org.folio.search.service.setter.AbstractLccnProcessor;
 import org.springframework.stereotype.Component;
@@ -22,7 +22,7 @@ public LccnAuthorityProcessor(ReferenceDataService referenceDataService) {
   }
 
   @Override
-  protected List<Identifiers> getIdentifiers(Authority authority) {
+  protected List<Identifier> getIdentifiers(Authority authority) {
     return Optional.ofNullable(authority)
       .map(Authority::getIdentifiers)
       .orElse(Collections.emptyList());

diff --git a/src/main/java/org/folio/search/service/setter/instance/ClassificationNumberProcessor.java b/src/main/java/org/folio/search/service/setter/instance/ClassificationNumberProcessor.java
@@ -6,8 +6,8 @@
 import java.util.Objects;
 import java.util.Set;
 import java.util.stream.Collectors;
+import org.folio.search.domain.dto.Classification;
 import org.folio.search.domain.dto.Instance;
-import org.folio.search.domain.dto.InstanceClassificationsInner;
 import org.folio.search.service.setter.FieldProcessor;
 import org.folio.search.utils.SearchUtils;
 import org.springframework.stereotype.Component;
@@ -17,9 +17,9 @@ public class ClassificationNumberProcessor implements FieldProcessor<Instance, S
 
   @Override
   public Set<String> getFieldValue(Instance instance) {
-    List<InstanceClassificationsInner> classifications = instance.getClassifications();
+    List<Classification> classifications = instance.getClassifications();
     return toStreamSafe(classifications)
-      .map(InstanceClassificationsInner::getClassificationNumber)
+      .map(Classification::getClassificationNumber)
       .map(SearchUtils::normalizeToAlphaNumeric)
       .filter(Objects::nonNull)
       .collect(Collectors.toSet());

diff --git a/src/main/java/org/folio/search/service/setter/instance/LccnInstanceProcessor.java b/src/main/java/org/folio/search/service/setter/instance/LccnInstanceProcessor.java
@@ -3,7 +3,7 @@
 import java.util.Collections;
 import java.util.List;
 import java.util.Optional;
-import org.folio.search.domain.dto.Identifiers;
+import org.folio.search.domain.dto.Identifier;
 import org.folio.search.domain.dto.Instance;
 import org.folio.search.integration.ReferenceDataService;
 import org.folio.search.service.setter.AbstractLccnProcessor;
@@ -25,7 +25,7 @@ public LccnInstanceProcessor(ReferenceDataService referenceDataService) {
   }
 
   @Override
-  protected List<Identifiers> getIdentifiers(Instance instance) {
+  protected List<Identifier> getIdentifiers(Instance instance) {
     return Optional.ofNullable(instance)
       .map(Instance::getIdentifiers)
       .orElse(Collections.emptyList());

diff --git a/src/main/java/org/folio/search/utils/SearchUtils.java b/src/main/java/org/folio/search/utils/SearchUtils.java
@@ -152,7 +152,7 @@ public static String getIndexName(ResourceEvent event) {
    * @return generated index name.
    */
   public static String getIndexName(String resource, String tenantId) {
-    return getFolioEnvName().toLowerCase(ROOT) + "_" + resource + "_" + tenantId;
+    return getFolioEnvName().toLowerCase(ROOT) + "_" + resource.toLowerCase(ROOT) + "_" + tenantId;
   }
 
   /**

diff --git a/src/main/resources/swagger.api/examples/request/browseConfigUpdateRequest.yaml b/src/main/resources/swagger.api/examples/request/browseConfigUpdateRequest.yaml
@@ -0,0 +1,6 @@
+value:
+  id: all
+  shelvingAlgorithm: default
+  typeIds:
+    - 7e5684a9-c8c1-4c1e-85b9-d047f53eeb6d
+    - 1faf5a71-01cc-4f14-82e8-38e26b6e3071