From 715dfecdbef6f5041bb276dccfc1a8e4b67d5de1 Mon Sep 17 00:00:00 2001
From: Michael Valdron <mvaldron@redhat.com>
Date: Thu, 21 Mar 2024 19:06:44 -0400
Subject: [PATCH] [WIP]REST doc update
Signed-off-by: Michael Valdron <mvaldron@redhat.com>
---
index/server/openapi.yaml | 48 ++++++++++--
index/server/registry-REST-API.adoc | 110 ++++++++++++++++++++++++++++
2 files changed, 152 insertions(+), 6 deletions(-)
diff --git a/index/server/openapi.yaml b/index/server/openapi.yaml
index 5f755001..000123fa 100644
--- 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,6 +1035,7 @@ components:
name: tags
in: query
required: false
+ description: Collection of search strings to filter stacks by their tags
schema:
type: array
items:
@@ -1040,14 +1043,14 @@ components:
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
index 56b6d479..df33e809 100644
--- 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