Skip to content
This repository has been archived by the owner on Jun 2, 2022. It is now read-only.

Commit

Permalink
Merge pull request #755 from ekinanp/gen-swagger-docs
Browse files Browse the repository at this point in the history 
Add swagger docs for the find endpoint
  • Loading branch information
@ekinanp
ekinanp committed Mar 11, 2020
2 parents 9761517 + a685ff2 commit 86aee5f
Show file tree
Hide file tree
Showing 5 changed files with 197 additions and 53 deletions.
19 changes: 17 additions & 2 deletions api/find.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,24 @@ import (
"github.com/puppetlabs/wash/plugin"
)

// swagger:route GET /fs/find find listEntries
// swagger:response
//nolint:deadcode,unused
type findResponse struct {
// in: body
Entries []apitypes.Entry
}

// swagger:parameters findResponse
//nolint:deadcode,unused
type findParams struct {
params
rql.Options
}

// swagger:route GET /fs/find find findResponse
//
// Recursively descends the given path returning it and its children.
// Recursively descends the given path, returning all children that satisfy
// the given RQL query.
//
// Consumes:
// - application/json
Expand Down
16 changes: 16 additions & 0 deletions api/rql/options.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,24 @@ package rql

// Options represent the RQL's options
type Options struct {
// Mindepth is the minimum depth. Descendants at lesser depths are not included
// in the RQL's returned list of entries.
//
// Depth starts from 0. For example, given paths "foo", "foo/bar", "foo/bar/baz",
// assume "foo" is the start path. Then "foo" is at depth 0, "foo/bar" is at depth 1,
// "foo/bar/baz" is at depth 2, etc.
Mindepth int
// Maxdepth is the maximum depth. Descendants at greater depths are not included
// in the RQL's returned list of entries. See Mindepth's comments to understand how
// depth is calculated.
Maxdepth int
// Fullmeta is short for "full metadata". If set, then meta primary queries act on
// the entry's full metadata, and the returned list of entries will include the entry's
// full metadata. If unset then the RQL uses the partial metadata instead.
//
// Note that setting Fullmeta could result in O(N) extra requests to fetch the metadata,
// where N is the number of visited entries. Using the partial metadata (unsetting Fullmeta)
// does not result in any extra request.
Fullmeta bool
}

Expand Down
4 changes: 2 additions & 2 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,8 @@ go get -u github.com/go-swagger/go-swagger/cmd/swagger

Then run it and [redoc-cli](https://github.com/Rebilly/ReDoc/blob/master/cli/README.md) from the project root to update the static docs page.
```
swagger generate spec > docs/docs/api.json
npx redoc-cli bundle docs/docs/api.json -o docs/docs/api.html --options.nativeScrollbars
swagger generate spec > docs/_docs/api.json
npx redoc-cli bundle docs/_docs/api.json -o docs/_docs/api.html --options.nativeScrollbars
```

## Extending the screencasts
Expand Down
119 changes: 76 additions & 43 deletions docs/_docs/api.html
View file

Large diffs are not rendered by default.

92 changes: 86 additions & 6 deletions docs/_docs/api.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -112,6 +112,66 @@
}
}
},
"/fs/find": {
"get": {
"description": "Recursively descends the given path, returning all children that satisfy\nthe given RQL query.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"schemes": [
"http"
],
"tags": [
"find"
],
"operationId": "findResponse",
"parameters": [
{
"type": "string",
"description": "uniquely identifies an entry",
"name": "Path",
"in": "query"
},
{
"type": "integer",
"format": "int64",
"description": "Mindepth is the minimum depth. Descendants at lesser depths are not included\nin the RQL's returned list of entries.\n\nDepth starts from 0. For example, given paths \"foo\", \"foo/bar\", \"foo/bar/baz\",\nassume \"foo\" is the start path. Then \"foo\" is at depth 0, \"foo/bar\" is at depth 1,\n\"foo/bar/baz\" is at depth 2, etc.",
"name": "Mindepth",
"in": "query"
},
{
"type": "integer",
"format": "int64",
"description": "Maxdepth is the maximum depth. Descendants at greater depths are not included\nin the RQL's returned list of entries. See Mindepth's comments to understand how\ndepth is calculated.",
"name": "Maxdepth",
"in": "query"
},
{
"type": "boolean",
"description": "Fullmeta is short for \"full metadata\". If set, then meta primary queries act on\nthe entry's full metadata, and the returned list of entries will include the entry's\nfull metadata. If unset then the RQL uses the partial metadata instead.\n\nNote that setting Fullmeta could result in O(N) extra requests to fetch the metadata,\nwhere N is the number of visited entries. Using the partial metadata (unsetting Fullmeta)\ndoes not result in any extra request.",
"name": "Fullmeta",
"in": "query"
}
],
"responses": {
"200": {
"$ref": "#/responses/entryList"
},
"400": {
"$ref": "#/responses/errorResp"
},
"404": {
"$ref": "#/responses/errorResp"
},
"500": {
"$ref": "#/responses/errorResp"
}
}
}
},
"/fs/info": {
"get": {
"description": "Returns an Entry object describing the given path.",
Expand Down Expand Up @@ -152,7 +212,7 @@
},
"/fs/list": {
"get": {
"description": "Returns a list of Entry objects describing children of the given path.",
"description": "Returns a list of Entry objects describing children of the given path.\nThe \"metadata\" key is set to the partial metadata.",
"produces": [
"application/json"
],
Expand Down Expand Up @@ -457,6 +517,13 @@
"type": "string",
"x-go-name": "CName"
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "object"
},
"x-go-name": "Metadata"
},
"name": {
"type": "string",
"x-go-name": "Name"
Expand All @@ -473,7 +540,7 @@
"x-go-package": "github.com/puppetlabs/wash/api/types"
},
"EntryAttributes": {
"description": "Each of the setters supports the builder pattern, which enables you\nto do something like\n\nattr := plugin.EntryAttributes{}\nattr.\nSetCrtime(crtime).\nSetMtime(mtime).\nSetMeta(meta)\nentry.SetAttributes(attr)",
"description": "Each of the setters supports the builder pattern, which enables you\nto do something like\n\nattr := plugin.EntryAttributes{}\nattr.\nSetCrtime(crtime).\nSetMtime(mtime)\nentry.SetAttributes(attr)",
"type": "object",
"title": "EntryAttributes represents an entry's attributes. We use a struct\ninstead of a map for efficient memory allocation/deallocation,\nwhich is needed to make Parent#List fast.",
"x-go-package": "github.com/puppetlabs/wash/plugin"
Expand Down Expand Up @@ -504,10 +571,10 @@
"type": "string",
"x-go-name": "Label"
},
"meta_attribute_schema": {
"metadata_schema": {
"$ref": "#/definitions/Schema"
},
"metadata_schema": {
"partial_metadata_schema": {
"$ref": "#/definitions/Schema"
},
"signals": {
Expand Down Expand Up @@ -1015,6 +1082,10 @@
"Entry": {
"description": "Entry represents a Wash entry as interpreted by the API.",
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
},
"$ref": "#/definitions/EntryAttributes"
},
"headers": {
Expand All @@ -1028,6 +1099,7 @@
"cname": {
"type": "string"
},
"metadata": {},
"name": {
"type": "string"
},
Expand Down Expand Up @@ -1071,10 +1143,10 @@
"label": {
"type": "string"
},
"metaAttributeSchemaObj": {},
"meta_attribute_schema": {},
"metadataSchemaObj": {},
"metadata_schema": {},
"partialMetadataSchemaObj": {},
"partial_metadata_schema": {},
"path": {
"type": "string"
},
Expand Down Expand Up @@ -1174,6 +1246,14 @@
}
}
},
"findResponse": {
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Entry"
}
}
},
"octetResponse": {
"schema": {
"$ref": "#/definitions/Reader"
Expand Down

0 comments on commit 86aee5f

Please sign in to comment.