Skip to content

Commit

Permalink
Descriptions in JSON Schema (#1633)
Browse files Browse the repository at this point in the history 
* chore: update schema generation library

Signed-off-by: Matej Vasek <mvasek@redhat.com>

* feat: description in JSON schema from doc comments

Signed-off-by: Matej Vasek <mvasek@redhat.com>

---------

Signed-off-by: Matej Vasek <mvasek@redhat.com>
  • Loading branch information
@matejvasek
matejvasek committed Mar 20, 2023
1 parent 99de349 commit 7c724bc
Show file tree
Hide file tree
Showing 10 changed files with 414 additions and 386 deletions.
2 changes: 1 addition & 1 deletion go.mod
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ require (
github.com/Masterminds/semver v1.5.0
github.com/Microsoft/go-winio v0.6.0
github.com/Netflix/go-expect v0.0.0-20220104043353-73e0943537d2
github.com/alecthomas/jsonschema v0.0.0-20210526225647-edb03dcab7bc
github.com/alecthomas/jsonschema v0.0.0-20220216202328-9eeeec9d044b
github.com/buildpacks/pack v0.28.0
github.com/cloudevents/sdk-go/v2 v2.13.0
github.com/containerd/containerd v1.6.10
Expand Down
4 changes: 2 additions & 2 deletions go.sum
View file
Original file line number Diff line number Diff line change
Expand Up @@ -210,8 +210,8 @@ github.com/acomagu/bufpipe v1.0.3 h1:fxAGrHZTgQ9w5QqVItgzwj235/uYZYgbXitB+dLupOk
github.com/acomagu/bufpipe v1.0.3/go.mod h1:mxdxdup/WdsKVreO5GpW4+M/1CE2sMG4jeGJ2sYmHc4=
github.com/agext/levenshtein v1.2.3 h1:YB2fHEn0UJagG8T1rrWknE3ZQzWM06O8AMAatNn7lmo=
github.com/agext/levenshtein v1.2.3/go.mod h1:JEDfjyjHDjOF/1e4FlBE/PkbqA9OfWu2ki2W0IB5558=
github.com/alecthomas/jsonschema v0.0.0-20210526225647-edb03dcab7bc h1:mT8qSzuyEAkxbv4GBln7yeuQZpBnfikr3PTuiPs6Z3k=
github.com/alecthomas/jsonschema v0.0.0-20210526225647-edb03dcab7bc/go.mod h1:/n6+1/DWPltRLWL/VKyUxg6tzsl5kHUCcraimt4vr60=
github.com/alecthomas/jsonschema v0.0.0-20220216202328-9eeeec9d044b h1:doCpXjVwui6HUN+xgNsNS3SZ0/jUZ68Eb+mJRNOZfog=
github.com/alecthomas/jsonschema v0.0.0-20220216202328-9eeeec9d044b/go.mod h1:/n6+1/DWPltRLWL/VKyUxg6tzsl5kHUCcraimt4vr60=
github.com/alecthomas/kingpin v2.2.6+incompatible/go.mod h1:59OFYbFVLKQKq+mqrL6Rw5bR0c3ACQaawgXx0QYndlE=
github.com/alecthomas/template v0.0.0-20160405071501-a0175ee3bccc/go.mod h1:LOuyumcjzFXgccqObfd/Ljyb9UuFJ6TxHnclSeseNhc=
github.com/alecthomas/template v0.0.0-20190718012654-fb15b899a751/go.mod h1:LOuyumcjzFXgccqObfd/Ljyb9UuFJ6TxHnclSeseNhc=
Expand Down
88 changes: 59 additions & 29 deletions schema/func_yaml-schema.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,39 +11,45 @@
"properties": {
"git": {
"$schema": "http://json-schema.org/draft-04/schema#",
"$ref": "#/definitions/Git"
"$ref": "#/definitions/Git",
"description": "Git stores information about an optionally associated git repository."
},
"builderImages": {
"patternProperties": {
".*": {
"type": "string"
}
},
"type": "object"
"type": "object",
"description": "BuilderImages define optional explicit builder images to use by\nbuilder implementations in leau of the in-code defaults. They key\nis the builder's short name. For example:\nbuilderImages:\n pack: example.com/user/my-pack-node-builder\n s2i: example.com/user/my-s2i-node-builder"
},
"buildpacks": {
"items": {
"type": "string"
},
"type": "array"
"type": "array",
"description": "Optional list of buildpacks to use when building the function"
},
"builder": {
"enum": [
"pack",
"s2i"
],
"type": "string"
"type": "string",
"description": "Builder is the name of the subsystem that will complete the underlying\nbuild (pack, s2i, etc)"
},
"buildEnvs": {
"items": {
"$schema": "http://json-schema.org/draft-04/schema#",
"$ref": "#/definitions/Env"
},
"type": "array"
"type": "array",
"description": "Build Env variables to be set"
}
},
"additionalProperties": false,
"type": "object"
"type": "object",
"description": "BuildSpec"
},
"DeploySpec": {
"required": [
Expand All @@ -56,37 +62,44 @@
],
"properties": {
"namespace": {
"type": "string"
"type": "string",
"description": "Namespace into which the function is deployed on supported platforms."
},
"remote": {
"type": "boolean"
"type": "boolean",
"description": "Remote indicates the deployment (and possibly build) process are to\nbe triggered in a remote environment rather than run locally."
},
"annotations": {
"patternProperties": {
".*": {
"type": "string"
}
},
"type": "object"
"type": "object",
"description": "Map containing user-supplied annotations\nExample: { \"division\": \"finance\" }"
},
"options": {
"$schema": "http://json-schema.org/draft-04/schema#",
"$ref": "#/definitions/Options"
"$ref": "#/definitions/Options",
"description": "Options to be set on deployed function (scaling, etc.)"
},
"labels": {
"items": {
"$schema": "http://json-schema.org/draft-04/schema#",
"$ref": "#/definitions/Label"
},
"type": "array"
"type": "array",
"description": "Map of user-supplied labels"
},
"healthEndpoints": {
"$schema": "http://json-schema.org/draft-04/schema#",
"$ref": "#/definitions/HealthEndpoints"
"$ref": "#/definitions/HealthEndpoints",
"description": "Health endpoints specified by the language pack"
}
},
"additionalProperties": false,
"type": "object"
"type": "object",
"description": "DeploySpec"
},
"Env": {
"required": [
Expand Down Expand Up @@ -119,46 +132,58 @@
],
"properties": {
"specVersion": {
"type": "string"
"type": "string",
"description": "SpecVersion at which this function is known to be compatible.\nMore specifically, it is the highest migration which has been applied.\nFor details see the .Migrated() and .Migrate() methods."
},
"name": {
"pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
"type": "string"
"type": "string",
"description": "Name of the function."
},
"runtime": {
"type": "string"
"type": "string",
"description": "Runtime is the language plus context. nodejs|go|quarkus|rust etc."
},
"registry": {
"type": "string"
"type": "string",
"description": "Registry at which to store interstitial containers, in the form\n[registry]/[user]."
},
"image": {
"type": "string"
"type": "string",
"description": "Optional full OCI image tag in form:\n [registry]/[namespace]/[name]:[tag]\nexample:\n quay.io/alice/my.function.name\nRegistry is optional and is defaulted to DefaultRegistry\nexample:\n alice/my.function.name\nIf Image is provided, it overrides the default of concatenating\n\"Registry+Name:latest\" to derive the Image."
},
"imageDigest": {
"type": "string"
"type": "string",
"description": "SHA256 hash of the latest image that has been built"
},
"created": {
"type": "string",
"description": "Created time is the moment that creation was successfully completed\naccording to the client which is in charge of what constitutes being\nfully \"Created\" (aka initialized)",
"format": "date-time"
},
"invoke": {
"type": "string"
"type": "string",
"description": "Invoke defines hints for use when invoking this function.\nSee Client.Invoke for usage."
},
"build": {
"$schema": "http://json-schema.org/draft-04/schema#",
"$ref": "#/definitions/BuildSpec"
"$ref": "#/definitions/BuildSpec",
"description": "BuildSpec define the build properties for a function"
},
"run": {
"$schema": "http://json-schema.org/draft-04/schema#",
"$ref": "#/definitions/RunSpec"
"$ref": "#/definitions/RunSpec",
"description": "RunSpec define the runtime properties for a function"
},
"deploy": {
"$schema": "http://json-schema.org/draft-04/schema#",
"$ref": "#/definitions/DeploySpec"
"$ref": "#/definitions/DeploySpec",
"description": "DeploySpec define the deployment properties for a function"
}
},
"additionalProperties": false,
"type": "object"
"type": "object",
"description": "Function"
},
"Git": {
"properties": {
Expand All @@ -185,7 +210,8 @@
}
},
"additionalProperties": false,
"type": "object"
"type": "object",
"description": "HealthEndpoints specify the liveness and readiness endpoints for a Runtime"
},
"Label": {
"required": [
Expand All @@ -194,7 +220,8 @@
"properties": {
"key": {
"pattern": "^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*\\/)?([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9]$",
"type": "string"
"type": "string",
"description": "Key consist of optional prefix part (ended by '/') and name part\nPrefix part validation pattern: [a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*\nName part validation pattern: ([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9]"
},
"value": {
"pattern": "^(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])?$",
Expand Down Expand Up @@ -275,17 +302,20 @@
"$schema": "http://json-schema.org/draft-04/schema#",
"$ref": "#/definitions/Volume"
},
"type": "array"
"type": "array",
"description": "List of volumes to be mounted to the function"
},
"envs": {
"items": {
"$ref": "#/definitions/Env"
},
"type": "array"
"type": "array",
"description": "Env variables to be set"
}
},
"additionalProperties": false,
"type": "object"
"type": "object",
"description": "RunSpec"
},
"ScaleOptions": {
"properties": {
Expand Down
11 changes: 10 additions & 1 deletion schema/generator/main.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ package main
import (
"bytes"
"encoding/json"
"fmt"
"os"

"github.com/alecthomas/jsonschema"
Expand All @@ -23,7 +24,15 @@ func main() {
// Genereated schema is written into schema/func_yaml-schema.json file
func generateFuncYamlSchema() error {
// generate json schema for function struct
js := jsonschema.Reflect(&fn.Function{})
r := &jsonschema.Reflector{}

err := r.AddGoComments("knative.dev/func", "./pkg/functions/")
if err != nil {
return fmt.Errorf("cannot parse docstrings: %w", err)
}

js := r.Reflect(&fn.Function{})

schema, err := js.MarshalJSON()
if err != nil {
return err
Expand Down
88 changes: 88 additions & 0 deletions vendor/github.com/alecthomas/jsonschema/.golangci.yml
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

5 changes: 0 additions & 5 deletions vendor/github.com/alecthomas/jsonschema/.travis.yml
View file

This file was deleted.

Loading

0 comments on commit 7c724bc

Please sign in to comment.