Merge pull request #1031 from amvanbaren/vscode-adapter-docs

VSCodeAPI documentation

server/src/dev/resources/application.yml

@@ -76,6 +76,7 @@ management:
             requests: true
 
 springdoc:
+  model-and-view-allowed: true
   swagger-ui:
     path: /swagger-ui
     docExpansion: list

server/src/main/java/org/eclipse/openvsx/adapter/ExtensionQueryParam.java

@@ -9,11 +9,19 @@
  ********************************************************************************/
 package org.eclipse.openvsx.adapter;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
 import java.util.Collections;
 import java.util.List;
 import java.util.stream.Collectors;
 
-public record ExtensionQueryParam(List<Filter> filters, int flags) {
+@Schema(description = "Parameters of the metadata query")
+public record ExtensionQueryParam(
+        @Schema(description = "List of query filters")
+        List<Filter> filters,
+        @Schema(description = "Flags to indicate what metadata to include in the query response")
+        int flags
+) {
 
 	public static final int FLAG_INCLUDE_VERSIONS = 0x1;
 	public static final int FLAG_INCLUDE_FILES = 0x2;
@@ -27,7 +35,27 @@ public record ExtensionQueryParam(List<Filter> filters, int flags) {
 	public static final int FLAG_INCLUDE_LATEST_VERSION_ONLY = 0x200;
 	public static final int FLAG_UNPUBLISHED = 0x1000;
 
-    public record Filter(List<Criterion> criteria, int pageNumber, int pageSize, int sortBy, int sortOrder) {
+    @Schema(description = "Query filter")
+    public record Filter(
+            @Schema(description = "List of filter criteria")
+            List<Criterion> criteria,
+            @Schema(description = "Page number")
+            int pageNumber,
+            @Schema(description = "Maximal number of results per page")
+            int pageSize,
+            @Schema(
+                    defaultValue = "0",
+                    allowableValues = {"0", "4", "5", "6"},
+                    description = "Query result sort key<br/><br/>values:<br/>* 0 Relevance<br/>* 4 InstallCount<br/>* 5 PublishedDate<br/>* 6 AverageRating"
+            )
+            int sortBy,
+            @Schema(
+                    defaultValue = "0",
+                    allowableValues = {"0", "1"},
+                    description = "Query result sort order<br/><br/>values:<br/>* 0 Descending<br/>* 1 Ascending"
+            )
+            int sortOrder
+    ) {
 
         public String findCriterion(int type) {
             if (criteria == null || criteria.isEmpty())
@@ -49,7 +77,16 @@ public List<String> findCriteria(int type) {
         }
     }
 
-    public static record Criterion(int filterType, String value) {
+    @Schema(description = "Filter criteria")
+    public record Criterion(
+            @Schema(
+                    allowableValues = {"1", "4", "5", "7", "8", "9", "10", "12"},
+                    description = "Filter type<br/><br/>values:<br/>* 1 TAG<br/>* 4 EXTENSION_ID<br/>* 5 CATEGORY<br/>* 7 EXTENSION_NAME<br/>* 8 TARGET<br/>* 9 FEATURED<br/>* 10 SEARCH_TEXT<br/>* 12 EXCLUDE_WITH_FLAGS"
+            )
+            int filterType,
+            @Schema(description = "Filter value")
+            String value
+    ) {
         public static final int FILTER_TAG = 1;
         public static final int FILTER_EXTENSION_ID = 4;
         public static final int FILTER_CATEGORY = 5;

server/src/main/java/org/eclipse/openvsx/adapter/ExtensionQueryResult.java

@@ -9,64 +9,128 @@
  ********************************************************************************/
 package org.eclipse.openvsx.adapter;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
 import java.util.List;
 
+import static org.eclipse.openvsx.util.TargetPlatform.*;
+
 // Keep interfaces in sync with
 // https://github.com/microsoft/vscode/blob/de0724b414e2f95f6cc484b03bccbc96686c2cfd/src/vs/platform/extensionManagement/common/extensionGalleryService.ts#L34-L81
 public record ExtensionQueryResult(List<ResultItem> results) {
 
     public record ResultItem(List<Extension> extensions, List<ResultMetadata> resultMetadata) {}
 
     public record Extension(
+            @Schema(description = "Extension identifier in the format {publisher}.{name}", example = "foo.bar")
             String extensionId,
+            @Schema(description = "Name of the extension")
             String extensionName,
+            @Schema(description = "Name to be displayed in user interfaces")
             String displayName,
+            @Schema(description = "Short description of the extension")
             String shortDescription,
             Publisher publisher,
             List<ExtensionVersion> versions,
             List<Statistic> statistics,
             List<String> tags,
+            @Schema(description = "Date and time when this extension was released (ISO-8601, same as published date)")
             String releaseDate,
+            @Schema(description = "Date and time when this extension was published (ISO-8601)")
             String publishedDate,
+            @Schema(description = "Date and time when this extension was last updated (ISO-8601)")
             String lastUpdated,
             List<String> categories,
+            @Schema(description = "Flag extension as preview")
             String flags
     ) {
         public static final String FLAG_PREVIEW = "preview";
     }
 
     public record Publisher(
+            @Schema(description = "Publisher name to be displayed in user interfaces")
             String displayName,
+            @Schema(description = "Public id of the publisher (UUID)")
             String publisherId,
+            @Schema(description = "Name of the publisher")
             String publisherName,
+            @Schema(description = "Web domain of the publisher, not implemented", allowableValues = {"null"})
             String domain,
+            @Schema(description = "Whether the publisher's web domain is verified, not implemented", allowableValues = {"null"})
             Boolean isDomainVerified
     ) {}
 
     public record ExtensionVersion(
             String version,
+            @Schema(description = "Date and time when this version was last updated (ISO-8601)")
             String lastUpdated,
+            @Schema(description = "URL to get extension version assets")
             String assetUri,
+            @Schema(description = "Fallback URL to get extension version assets")
             String fallbackAssetUri,
             List<ExtensionFile> files,
             List<Property> properties,
+            @Schema(description = "Name of the target platform", allowableValues = {
+                    NAME_WIN32_X64, NAME_WIN32_IA32, NAME_WIN32_ARM64,
+                    NAME_LINUX_X64, NAME_LINUX_ARM64, NAME_LINUX_ARMHF,
+                    NAME_ALPINE_X64, NAME_ALPINE_ARM64,
+                    NAME_DARWIN_X64, NAME_DARWIN_ARM64,
+                    NAME_WEB, NAME_UNIVERSAL
+            })
             String targetPlatform
     ) {}
 
-    public record ExtensionFile(String assetType, String source) {
+    public record ExtensionFile(
+            @Schema(
+                    description = "Type of the extension file",
+                    allowableValues = {
+                            FILE_ICON,
+                            FILE_DETAILS,
+                            FILE_CHANGELOG,
+                            FILE_MANIFEST,
+                            FILE_VSIX, FILE_LICENSE,
+                            FILE_WEB_RESOURCES,
+                            FILE_VSIXMANIFEST,
+                            FILE_SIGNATURE,
+                            FILE_PUBLIC_KEY
+                    }
+            )
+            String assetType,
+            @Schema(description = "URL to get the extension file")
+            String source
+    ) {
         public static final String FILE_ICON = "Microsoft.VisualStudio.Services.Icons.Default";
         public static final String FILE_DETAILS = "Microsoft.VisualStudio.Services.Content.Details";
         public static final String FILE_CHANGELOG = "Microsoft.VisualStudio.Services.Content.Changelog";
         public static final String FILE_MANIFEST = "Microsoft.VisualStudio.Code.Manifest";
         public static final String FILE_VSIX = "Microsoft.VisualStudio.Services.VSIXPackage";
         public static final String FILE_LICENSE = "Microsoft.VisualStudio.Services.Content.License";
-        public static final String FILE_WEB_RESOURCES = "Microsoft.VisualStudio.Code.WebResources/";
+        public static final String FILE_WEB_RESOURCES = "Microsoft.VisualStudio.Code.WebResources";
         public static final String FILE_VSIXMANIFEST = "Microsoft.VisualStudio.Services.VsixManifest";
         public static final String FILE_SIGNATURE = "Microsoft.VisualStudio.Services.VsixSignature";
         public static final String FILE_PUBLIC_KEY = "Microsoft.VisualStudio.Services.PublicKey";
     }
 
-    public record Property(String key, String value) {
+    public record Property(
+            @Schema(
+                    description = "Identifier of the property",
+                    allowableValues = {
+                            PROP_REPOSITORY,
+                            PROP_SPONSOR_LINK,
+                            PROP_DEPENDENCY,
+                            PROP_EXTENSION_PACK,
+                            PROP_ENGINE,
+                            PROP_LOCALIZED_LANGUAGES,
+                            PROP_BRANDING_COLOR,
+                            PROP_BRANDING_THEME,
+                            PROP_WEB_EXTENSION,
+                            PROP_PRE_RELEASE
+                    }
+            )
+            String key,
+            @Schema(description = "Value of the property")
+            String value
+    ) {
         public static final String PROP_REPOSITORY = "Microsoft.VisualStudio.Services.Links.Source";
         public static final String PROP_SPONSOR_LINK = "Microsoft.VisualStudio.Code.SponsorLink";
         public static final String PROP_DEPENDENCY = "Microsoft.VisualStudio.Code.ExtensionDependencies";
@@ -79,7 +143,12 @@ public record Property(String key, String value) {
         public static final String PROP_PRE_RELEASE = "Microsoft.VisualStudio.Code.PreRelease";
     }
 
-    public record Statistic(String statisticName, double value) {
+    public record Statistic(
+            @Schema(description = "Name of the statistic", allowableValues = {STAT_INSTALL, STAT_AVERAGE_RATING, STAT_RATING_COUNT})
+            String statisticName,
+            @Schema(description = "Value of the statistic")
+            double value
+    ) {
         public static final String STAT_INSTALL = "install";
         public static final String STAT_AVERAGE_RATING = "averagerating";
         public static final String STAT_RATING_COUNT = "ratingcount";

server/src/main/java/org/eclipse/openvsx/adapter/LocalVSCodeService.java

@@ -311,8 +311,8 @@ public ResponseEntity<StreamingResponseBody> getAsset(
         var type = assets.get(assetType);
         if(type != null) {
             resource = repositories.findFileByType(namespace, extensionName, targetPlatform, version, type);
-        } else if(asset.startsWith(FILE_WEB_RESOURCES + "extension/")) {
-            var name = asset.substring((FILE_WEB_RESOURCES.length()));
+        } else if(asset.startsWith(FILE_WEB_RESOURCES + "/extension/")) {
+            var name = asset.substring((FILE_WEB_RESOURCES.length() + 1));
             resource = repositories.findFileByTypeAndName(namespace, extensionName, targetPlatform, version, FileResource.RESOURCE, name);
         }