[WIP]REST doc update

Signed-off-by: Michael Valdron <[email protected]>
devfile · Mar 22, 2024 · 715dfec · 715dfec
1 parent 91a5525
commit 715dfec
Show file tree

Hide file tree

Showing 2 changed files with 152 additions and 6 deletions.
diff --git a/index/server/openapi.yaml b/index/server/openapi.yaml
@@ -108,8 +108,6 @@ paths:
         - $ref: '#/components/parameters/iconUriParam'
         - $ref: '#/components/parameters/projectTypeParam'
         - $ref: '#/components/parameters/languageParam'
-        - $ref: '#/components/parameters/minSchemaVersionParam'
-        - $ref: '#/components/parameters/maxSchemaVersionParam'
         - $ref: '#/components/parameters/resourcesParam'
         - $ref: '#/components/parameters/starterProjectsParam'
         - $ref: '#/components/parameters/linkNamesParam'
@@ -174,8 +172,6 @@ paths:
         - $ref: '#/components/parameters/iconUriParam'
         - $ref: '#/components/parameters/projectTypeParam'
         - $ref: '#/components/parameters/languageParam'
-        - $ref: '#/components/parameters/minSchemaVersionParam'
-        - $ref: '#/components/parameters/maxSchemaVersionParam'
         - $ref: '#/components/parameters/resourcesParam'
         - $ref: '#/components/parameters/starterProjectsParam'
         - $ref: '#/components/parameters/linkNamesParam'
@@ -1007,24 +1003,30 @@ components:
       name: name
       in: query
       required: false
+      description: Search string to filter stacks by their name
       schema:
         $ref: '#/components/schemas/Name'
     displayNameParam:
       name: displayName
       in: query
       required: false
+      description: Search string to filter stacks by their display names
       schema:
         $ref: '#/components/schemas/DisplayName'
     descriptionParam:
       name: description
       in: query
       required: false
+      description: Search string to filter stacks by the description text
       schema:
         $ref: '#/components/schemas/Description'
     attributeNamesParam:
       name: attributeNames
       in: query
       required: false
+      description: |-
+        Collection of search strings to filter stacks by the names of 
+        defined free-form attributes
       schema:
         type: array
         items:
@@ -1033,21 +1035,22 @@ components:
       name: tags
       in: query
       required: false
+      description: Collection of search strings to filter stacks by their tags
       schema:
         type: array
         items:
           type: string
     iconParam:
       name: icon
       in: query
-      description: The icon encoding filter
+      description: Toggle on encoding content passed
       required: false
       schema:
         $ref: '#/components/schemas/Icon'
     iconUriParam:
       name: iconUri
       in: query
-      description: The icon uri filter
+      description: Search string to filter stacks by their icon uri
       required: false
       schema:
         $ref: '#/components/schemas/IconUri'
@@ -1062,36 +1065,42 @@ components:
       name: projectType
       in: query
       required: false
+      description: Search string to filter stacks by their project type
       schema:
         $ref: '#/components/schemas/ProjectType'
     languageParam:
       name: language
       in: query
       required: false
+      description: Search string to filter stacks by their programming language
       schema:
         $ref: '#/components/schemas/Language'
     minVersionParam:
       name: minVersion
       in: query
       required: false
+      description: The minimum stack version
       schema:
         $ref: '#/components/schemas/Version'
     maxVersionParam:
       name: maxVersion
       in: query
       required: false
+      description: The maximum stack version
       schema:
         $ref: '#/components/schemas/Version'
     minSchemaVersionParam:
       name: minSchemaVersion
       in: query
       required: false
+      description: The minimum devfile schema version
       schema:
         $ref: '#/components/schemas/SchemaVersion'
     maxSchemaVersionParam:
       name: maxSchemaVersion
       in: query
       required: false
+      description: The maximum devfile schema version
       schema:
         $ref: '#/components/schemas/SchemaVersion'
     defaultParam:
@@ -1104,24 +1113,36 @@ components:
       name: resources
       in: query
       required: false
+      description: |- 
+        Collection of search strings to filter stacks by their 
+        resource files
       schema:
         $ref: '#/components/schemas/Resources'
     starterProjectsParam:
       name: starterProjects
       in: query
       required: false
+      description: |-
+        Collection of search strings to filter stacks by the names 
+        of the starter projects
       schema:
         $ref: '#/components/schemas/StarterProjects'
     linkNamesParam:
       name: linkNames
       in: query
       required: false
+      description: |-
+        Collection of search strings to filter stacks by the names 
+        of the link sources
       schema:
         $ref: '#/components/schemas/LinkNames'
     linksParam:
       name: links
       in: query
       required: false
+      description: |- 
+        Collection of search strings to filter stacks by their link 
+        sources
       schema:
         $ref: '#/components/schemas/Links'
     commandGroupsParam:
@@ -1134,48 +1155,63 @@ components:
       name: gitRemoteNames
       in: query
       required: false
+      description: |-
+        Collection of search strings to filter stacks by the names of 
+        the git remotes
       schema:
         $ref: '#/components/schemas/GitRemoteNames'
     gitRemotesParam:
       name: gitRemotes
       in: query
       required: false
+      description: |-
+        Collection of search strings to filter stacks by the URIs of 
+        the git remotes
       schema:
         $ref: '#/components/schemas/GitRemotes'
     gitUrlParam:
       name: gitUrl
       in: query
       required: false
+      description: Search string to filter stacks by their git urls
       schema:
         $ref: '#/components/schemas/Url'
     gitRemoteNameParam:
       name: gitRemoteName
       in: query
       required: false
+      description: |- 
+        Search string to filter stacks by their git remote name
       schema:
         $ref: '#/components/schemas/GitRemoteName'
     gitSubDirParam:
       name: gitSubDir
       in: query
       required: false
+      description: |-
+        Search string to filter stacks by their target subdirectory 
+        of the git repository
       schema:
         $ref: '#/components/schemas/GitSubDir'
     gitRevisionParam:
       name: gitRevision
       in: query
       required: false
+      description: Search string to filter stacks by their git revision
       schema:
         $ref: '#/components/schemas/GitRevision'
     providerParam:
       name: provider
       in: query
       required: false
+      description: Search string to filter stacks by the stack provider
       schema:
         $ref: '#/components/schemas/Provider'
     supportUrlParam:
       name: supportUrl
       in: query
       required: false
+      description: Search string to filter stacks by their given support url
       schema:
         $ref: '#/components/schemas/Url'
   responses:

diff --git a/index/server/registry-REST-API.adoc b/index/server/registry-REST-API.adoc
@@ -323,6 +323,116 @@ curl http://devfile-registry.192.168.1.1.nip.io/index
 ]
 ----
 
+=== Query parameters
+[cols="1,1"]
+|===
+|Parameter|Description
+
+|Name
+|Search string to filter stacks by their name
+
+|DisplayName
+|Search string to filter stacks by their display names
+
+|Description
+|Search string to filter stacks by the description text
+
+|AttributeNames
+|Collection of search strings to filter stacks by the names of defined free-form attributes
+
+|Tags
+|Collection of search strings to filter stacks by their tags
+
+|Icon
+|Toggle on encoding content passed
+
+|IconUri
+|Search string to filter stacks by their icon uri
+
+|ProjectType
+|Search string to filter stacks by their project type
+
+|Language
+|Search string to filter stacks by their programming language
+
+|Resources
+|Collection of search strings to filter stacks by their resource files
+
+|StarterProjects
+|Collection of search strings to filter stacks by the names of the starter projects
+
+|LinkNames
+|Collection of search strings to filter stacks by the names of the link sources
+
+|Links
+|Collection of search strings to filter stacks by their link sources
+
+|GitRemoteNames
+|Collection of search strings to filter stacks by the names of the git remotes
+
+|GitRemotes
+|Collection of search strings to filter stacks by the URIs of the git remotes
+
+|GitUrl
+|Search string to filter stacks by their git urls
+
+|GitRemoteName
+|Search string to filter stacks by their git remote name
+
+|GitSubDir
+|Search string to filter stacks by their target subdirectory of the git repository
+
+|GitRevision
+|Search string to filter stacks by their git revision
+
+|Provider
+|Search string to filter stacks by the stack provider
+
+|SupportUrl
+|Search string to filter stacks by their given support url
+
+|===
+
+=== Request example
+....
+curl http://devfile-registry.192.168.1.1.nip.io/index?provider=Red%22Hat&resources=.zip
+....
+
+*Note:* Field filter parameters accept fuzzy search strings, meaning if `.zip` is passed into `resources` parameter, the results will be any stack with resource entries which contain `.zip` as partial matches.
+
+=== Response example
+[source,json]
+----
+[
+  {
+    "name": "go",
+    "version": "1.2.0",
+    "displayName": "Go Runtime",
+    "description": "Go is an open source programming language that makes it easy to build simple, reliable, and efficient software.",
+    "type": "stack",
+    "tags": [
+      "testtag"
+    ],
+    "icon": "https://raw.githubusercontent.com/devfile-samples/devfile-stack-icons/main/golang.svg",
+    "projectType": "Go",
+    "language": "Go",
+    "links": {
+      "self": "devfile-catalog/go:1.2.0"
+    },
+    "resources": [
+      "devfile.yaml",
+      "go-starter-offline.zip"
+    ],
+    "starterProjects": [
+      "go-starter",
+      "go-starter-offline"
+    ],
+    "provider": "Red Hat"
+  }
+]
+----
+
+
 == Gets registry index of sample devfile type
 Gets the registry index file content of sample devfile type from HTTP response