From 17995f785f6fdc0619aa78b9be2fcb6108e242e7 Mon Sep 17 00:00:00 2001 From: Alan Conway Date: Wed, 28 Aug 2024 18:46:04 -0400 Subject: [PATCH] doc: Fix type descriptions in generated REST API doc --- Makefile | 2 +- doc/README.adoc | 1 + doc/gen/rest_api.adoc | 93 +++++++++++++++++++++++++++----- etc/swagger/markdown/docs.gotmpl | 26 ++++----- internal/pkg/build/version.txt | 2 +- pkg/korrel8r/constraint.go | 10 ++-- pkg/rest/docs/docs.go | 67 ++++++++++++++++++++++- pkg/rest/docs/swagger.json | 67 ++++++++++++++++++++++- pkg/rest/docs/swagger.yaml | 48 +++++++++++++++++ pkg/rest/model.go | 8 +-- 10 files changed, 283 insertions(+), 41 deletions(-) create mode 120000 doc/README.adoc diff --git a/Makefile b/Makefile index 3aae562a..53955af8 100644 --- a/Makefile +++ b/Makefile @@ -6,7 +6,7 @@ help: ## Display this help. @grep -E '^## [A-Z0-9_]+: ' Makefile | sed 's/^## \([A-Z0-9_]*\): \(.*\)/\1#\2/' | column -s'#' -t ## VERSION: Semantic version for release, use -dev for development pre-release versions. -VERSION?=0.7.2 +VERSION?=0.7.3-dev ## REGISTRY: Name of image registry REGISTRY?=quay.io ## REGISTRY_ORG: Name of registry organization. diff --git a/doc/README.adoc b/doc/README.adoc new file mode 120000 index 00000000..1323301c --- /dev/null +++ b/doc/README.adoc @@ -0,0 +1 @@ +index.adoc \ No newline at end of file diff --git a/doc/gen/rest_api.adoc b/doc/gen/rest_api.adoc index 030a787a..7792bff0 100644 --- a/doc/gen/rest_api.adoc +++ b/doc/gen/rest_api.adoc @@ -106,7 +106,7 @@ GET /api/v1alpha1/domains/{domain}/classes | `string` | | required -| +| | Domain name |=== @@ -167,7 +167,7 @@ GET /api/v1alpha1/objects | `string` | | required -| +| | query string |=== @@ -228,7 +228,7 @@ POST /api/v1alpha1/graphs/goals | `bool` | | optional -| +| | include rules in graph edges | request | `body` | link:#goals[Goals] | `models.Goals` | | ✓ | | search from start to goal classes @@ -291,7 +291,7 @@ POST /api/v1alpha1/graphs/neighbours | `bool` | | optional -| +| | include rules in graph edges | request | `body` | link:#neighbours[Neighbours] | `models.Neighbours` | | ✓ | | search from neighbours @@ -395,18 +395,45 @@ any === Classes -> Classes is a map from class names to a short description. +Classes is a map from class names to a short description. link:#classes[Classes] +[id=constraint] +=== Constraint + + +Constraint constrains the objects that will be included in search results. + + + + + + +**Properties** + +[%autowidth] +|=== +| Name | Type | Go type | Required | Default | Description | Example + + | end | date-time (formatted string)| `strfmt.DateTime` | | | End of time interval, quoted RFC 3339 format. | + + | limit | integer| `int64` | | | Limit number of objects returned per query, <=0 means no limit. | + + | start | date-time (formatted string)| `strfmt.DateTime` | | | Start of time interval, quoted RFC 3339 format. | + + | timeout | string| `string` | | | Timeout per request, h/m/s/ms/ns format | + +|=== + [id=domain] === Domain -> Domain configuration information. +Domain configuration information. @@ -429,7 +456,7 @@ link:#classes[Classes] === Edge -> Directed edge in the result graph, from Start to Goal classes. +Directed edge in the result graph, from Start to Goal classes. @@ -454,15 +481,30 @@ link:#classes[Classes] === Goals +Starting point for a goals search. -link:#interface[interface{}] + + + + +**Properties** + +[%autowidth] +|=== +| Name | Type | Go type | Required | Default | Description | Example + + | goals | []string| `[]string` | | | Goal classes for correlation. | `["domain:class"]` + + | start | link:#start[Start]| `Start` | | | | + +|=== [id=graph] === Graph -> Graph resulting from a correlation search. +Graph resulting from a correlation search. @@ -485,7 +527,7 @@ link:#interface[interface{}] === Neighbours -> Starting point for a neighbours search. +Starting point for a neighbours search. @@ -508,10 +550,13 @@ link:#interface[interface{}] === Node +Node in the result graph, contains results for a single class. + + **Properties** [%autowidth] @@ -530,7 +575,7 @@ link:#interface[interface{}] === QueryCount -> Query run during a correlation with a count of results found. +Query run during a correlation with a count of results found. @@ -553,10 +598,13 @@ link:#interface[interface{}] === Rule +Rule is a correlation rule with a list of queries and results counts found during navigation. + + **Properties** [%autowidth] @@ -573,15 +621,34 @@ link:#interface[interface{}] === Start +Start identifies a set of starting objects for correlation. -link:#interface[interface{}] + + + + +**Properties** + +[%autowidth] +|=== +| Name | Type | Go type | Required | Default | Description | Example + + | class | string| `string` | | | Class for `objects` | + + | constraint | link:#constraint[Constraint]| `Constraint` | | | | + + | objects | link:#interface[interface{}]| `interface{}` | | | Objects of `class` serialized as JSON | + + | queries | []string| `[]string` | | | Queries for starting objects | + +|=== [id=store] === Store -> Store is a map of name:value attributes used to connect to a store. +Store is a map of name:value attributes used to connect to a store. diff --git a/etc/swagger/markdown/docs.gotmpl b/etc/swagger/markdown/docs.gotmpl index 8b536c0f..b709d809 100644 --- a/etc/swagger/markdown/docs.gotmpl +++ b/etc/swagger/markdown/docs.gotmpl @@ -7,12 +7,12 @@ https://github.com/go-swagger/go-swagger/blob/master/generator/templates/markdow {{- with .ExternalDocs }} {{- if .URL }} {{- if .Description }} - > {{ .URL }}[{{ trimSpace .Description }}] + {{ .URL }}[{{ trimSpace .Description }}] {{- else }} - > {{ .URL }}[Read more] + {{ .URL }}[Read more] {{- end }} {{- else }} -> {{ trimSpace .Description }} +{{ trimSpace .Description }} {{- end }} {{- end }} {{- end }} @@ -25,7 +25,7 @@ https://github.com/go-swagger/go-swagger/blob/master/generator/templates/markdow | `{{ .GoType }}` | {{ if .CollectionFormat }}`{{ docCollectionFormat .CollectionFormat .Child }}`{{ end }} | {{ if .Required }}required{{else}}optional{{ end }} -| {{ if .Default }}`{{ json .Default }}`{{ end }} +| {{ if .Default }}`{{ json .Default }}`{{ end }} | {{ trimSpace .Description }} {{- end }} @@ -148,7 +148,7 @@ any {{- define "docModel" }}{{/* renders a definition */}} {{- with .Description }} -> {{ .}} +{{ .}} {{- end }} {{- if .ExternalDocs }} {{ template "externalDoc" . }} @@ -297,20 +297,20 @@ Produces:: {{- with .Type }} -> **Type**: {{ . }} +**Type**: {{ . }} {{- end }} {{- if .IsOAuth2}} {{- with .Flow }} - > - > **Flow**: {{ . }} + + **Flow**: {{ . }} {{- end }} {{- with .AuthorizationURL }} - > - > **Authorization URL**: {{ . }} + + **Authorization URL**: {{ . }} {{- end }} {{- with .TokenURL }} - > - > **Token URL**: {{ . }} + + **Token URL**: {{ . }} {{- end }} {{ if .ScopesDesc }} @@ -384,7 +384,7 @@ Produces:: {{- with .ExternalDocs }} -> {{ if .URL }}[Read more]({{ .URL }} "{{ .Description }}"){{ end }} +{{ if .URL }}[Read more]({{ .URL }} "{{ .Description }}"){{ end }} {{- end }} {{- if or (gt (len .SchemeOverrides) 0) (gt (len .ExtraSchemeOverrides) 0) }} diff --git a/internal/pkg/build/version.txt b/internal/pkg/build/version.txt index 7486fdbc..c4181d00 100644 --- a/internal/pkg/build/version.txt +++ b/internal/pkg/build/version.txt @@ -1 +1 @@ -0.7.2 +0.7.3-dev diff --git a/pkg/korrel8r/constraint.go b/pkg/korrel8r/constraint.go index 9f4eee79..42f38c06 100644 --- a/pkg/korrel8r/constraint.go +++ b/pkg/korrel8r/constraint.go @@ -8,12 +8,12 @@ import ( "github.com/korrel8r/korrel8r/pkg/ptr" ) -// Constraint included in a reference to restrict the resulting objects. +// Constraint included in a store Get operation to restrict the resulting objects. type Constraint struct { - Limit *int `json:"limit,omitempty"` // Limit number of objects returned per query, <=0 means no limit. - Timeout *time.Duration `json:"timeout,omitempty"` // Timeout per request. - Start *time.Time `json:"start,omitempty"` // Start of time interval to include. - End *time.Time `json:"end,omitempty"` // End of time interval to include. + Limit *int `json:"limit,omitempty"` // Limit number of objects returned per query, <=0 means no limit. + Timeout *time.Duration `json:"timeout,omitempty" swaggertype:"string"` // Timeout per request, h/m/s/ms/ns format + Start *time.Time `json:"start,omitempty" swaggertype:"string" format:"date-time"` // Start of time interval, quoted RFC 3339 format. + End *time.Time `json:"end,omitempty" swaggertype:"string" format:"date-time"` // End of time interval, quoted RFC 3339 format. } // CompareTime returns -1 if t is before the constraint interval, +1 if it is after, diff --git a/pkg/rest/docs/docs.go b/pkg/rest/docs/docs.go index 7428c262..75b44d4f 100644 --- a/pkg/rest/docs/docs.go +++ b/pkg/rest/docs/docs.go @@ -223,6 +223,30 @@ const docTemplate = `{ "type": "string" } }, + "Constraint": { + "description": "Constraint constrains the objects that will be included in search results.", + "type": "object", + "properties": { + "end": { + "description": "End of time interval, quoted RFC 3339 format.", + "type": "string", + "format": "date-time" + }, + "limit": { + "description": "Limit number of objects returned per query, \u003c=0 means no limit.", + "type": "integer" + }, + "start": { + "description": "Start of time interval, quoted RFC 3339 format.", + "type": "string", + "format": "date-time" + }, + "timeout": { + "description": "Timeout per request, h/m/s/ms/ns format", + "type": "string" + } + } + }, "Domain": { "description": "Domain configuration information.", "type": "object", @@ -264,7 +288,23 @@ const docTemplate = `{ } }, "Goals": { - "type": "object" + "description": "Starting point for a goals search.", + "type": "object", + "properties": { + "goals": { + "description": "Goal classes for correlation.", + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "domain:class" + ] + }, + "start": { + "$ref": "#/definitions/Start" + } + } }, "Graph": { "description": "Graph resulting from a correlation search.", @@ -298,6 +338,7 @@ const docTemplate = `{ } }, "Node": { + "description": "Node in the result graph, contains results for a single class.", "type": "object", "properties": { "class": { @@ -333,6 +374,7 @@ const docTemplate = `{ } }, "Rule": { + "description": "Rule is a correlation rule with a list of queries and results counts found during navigation.", "type": "object", "properties": { "name": { @@ -349,7 +391,28 @@ const docTemplate = `{ } }, "Start": { - "type": "object" + "description": "Start identifies a set of starting objects for correlation.", + "type": "object", + "properties": { + "class": { + "description": "Class for ` + "`" + `objects` + "`" + `", + "type": "string" + }, + "constraint": { + "$ref": "#/definitions/Constraint" + }, + "objects": { + "description": "Objects of ` + "`" + `class` + "`" + ` serialized as JSON", + "type": "object" + }, + "queries": { + "description": "Queries for starting objects", + "type": "array", + "items": { + "type": "string" + } + } + } }, "Store": { "description": "Store is a map of name:value attributes used to connect to a store.", diff --git a/pkg/rest/docs/swagger.json b/pkg/rest/docs/swagger.json index 06d6b4c3..f62131c5 100644 --- a/pkg/rest/docs/swagger.json +++ b/pkg/rest/docs/swagger.json @@ -221,6 +221,30 @@ "type": "string" } }, + "Constraint": { + "description": "Constraint constrains the objects that will be included in search results.", + "type": "object", + "properties": { + "end": { + "description": "End of time interval, quoted RFC 3339 format.", + "type": "string", + "format": "date-time" + }, + "limit": { + "description": "Limit number of objects returned per query, \u003c=0 means no limit.", + "type": "integer" + }, + "start": { + "description": "Start of time interval, quoted RFC 3339 format.", + "type": "string", + "format": "date-time" + }, + "timeout": { + "description": "Timeout per request, h/m/s/ms/ns format", + "type": "string" + } + } + }, "Domain": { "description": "Domain configuration information.", "type": "object", @@ -262,7 +286,23 @@ } }, "Goals": { - "type": "object" + "description": "Starting point for a goals search.", + "type": "object", + "properties": { + "goals": { + "description": "Goal classes for correlation.", + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "domain:class" + ] + }, + "start": { + "$ref": "#/definitions/Start" + } + } }, "Graph": { "description": "Graph resulting from a correlation search.", @@ -296,6 +336,7 @@ } }, "Node": { + "description": "Node in the result graph, contains results for a single class.", "type": "object", "properties": { "class": { @@ -331,6 +372,7 @@ } }, "Rule": { + "description": "Rule is a correlation rule with a list of queries and results counts found during navigation.", "type": "object", "properties": { "name": { @@ -347,7 +389,28 @@ } }, "Start": { - "type": "object" + "description": "Start identifies a set of starting objects for correlation.", + "type": "object", + "properties": { + "class": { + "description": "Class for `objects`", + "type": "string" + }, + "constraint": { + "$ref": "#/definitions/Constraint" + }, + "objects": { + "description": "Objects of `class` serialized as JSON", + "type": "object" + }, + "queries": { + "description": "Queries for starting objects", + "type": "array", + "items": { + "type": "string" + } + } + } }, "Store": { "description": "Store is a map of name:value attributes used to connect to a store.", diff --git a/pkg/rest/docs/swagger.yaml b/pkg/rest/docs/swagger.yaml index 8a40733b..8cbe1725 100644 --- a/pkg/rest/docs/swagger.yaml +++ b/pkg/rest/docs/swagger.yaml @@ -7,6 +7,25 @@ definitions: type: string description: Classes is a map from class names to a short description. type: object + Constraint: + description: Constraint constrains the objects that will be included in search + results. + properties: + end: + description: End of time interval, quoted RFC 3339 format. + format: date-time + type: string + limit: + description: Limit number of objects returned per query, <=0 means no limit. + type: integer + start: + description: Start of time interval, quoted RFC 3339 format. + format: date-time + type: string + timeout: + description: Timeout per request, h/m/s/ms/ns format + type: string + type: object Domain: description: Domain configuration information. properties: @@ -37,6 +56,17 @@ definitions: type: string type: object Goals: + description: Starting point for a goals search. + properties: + goals: + description: Goal classes for correlation. + example: + - domain:class + items: + type: string + type: array + start: + $ref: '#/definitions/Start' type: object Graph: description: Graph resulting from a correlation search. @@ -60,6 +90,7 @@ definitions: $ref: '#/definitions/Start' type: object Node: + description: Node in the result graph, contains results for a single class. properties: class: description: Class is the full class name in "DOMAIN:CLASS" form. @@ -85,6 +116,8 @@ definitions: type: string type: object Rule: + description: Rule is a correlation rule with a list of queries and results counts + found during navigation. properties: name: description: Name is an optional descriptive name. @@ -96,6 +129,21 @@ definitions: type: array type: object Start: + description: Start identifies a set of starting objects for correlation. + properties: + class: + description: Class for `objects` + type: string + constraint: + $ref: '#/definitions/Constraint' + objects: + description: Objects of `class` serialized as JSON + type: object + queries: + description: Queries for starting objects + items: + type: string + type: array type: object Store: additionalProperties: diff --git a/pkg/rest/model.go b/pkg/rest/model.go index 95b6e3ae..95fa36b0 100644 --- a/pkg/rest/model.go +++ b/pkg/rest/model.go @@ -57,12 +57,12 @@ type Neighbours struct { } // @name Neighbours -// Options control the format of the graph +// @description Options control the format of the graph type Options struct { Rules bool `form:"rules"` // Rules if true include rules in the graph edges. } // @name GraphOptions -// Objects requests objects corresponding to a query. +// @description Objects requests objects corresponding to a query. type Objects struct { Query string `form:"query"` // Query string to execute. Constraint *Constraint `json:"constraint,omitempty"` @@ -74,7 +74,7 @@ type QueryCount struct { Count int `json:"count"` // Count of results or -1 if the query was not executed. } // @name QueryCount -// Rule is a correlation rule with a list of queries and results counts found during navigation. +// @description Rule is a correlation rule with a list of queries and results counts found during navigation. // Rules form a directed multi-graph over classes in the result graph. type Rule struct { // Name is an optional descriptive name. @@ -83,7 +83,7 @@ type Rule struct { Queries []QueryCount `json:"queries,omitempty"` } // @name Rule -// Node in the result graph, contains results for a single class. +// @description Node in the result graph, contains results for a single class. type Node struct { // Class is the full class name in "DOMAIN:CLASS" form. Class string `json:"class" example:"domain:class"`