Merge branch 'main' into embedded-doc

invopop · Jan 30, 2024 · de24ea5 · de24ea5
2 parents 8078bcb + 9b6bb6e
commit de24ea5
Show file tree

Hide file tree

Showing 40 changed files with 1,250 additions and 384 deletions.
diff --git a/.github/workflows/lint.yaml b/.github/workflows/lint.yaml
@@ -12,10 +12,15 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - name: Check out code
-      uses: actions/checkout@v2
+      - uses: actions/setup-go@v4
+        with:
+          go-version: "1.18"
+          cache: false
 
-    - name: Lint
-      uses: golangci/golangci-lint-action@v2
-      with:
-        version: v1.45
+      - name: Check out code
+        uses: actions/checkout@v3
+
+      - name: Lint
+        uses: golangci/golangci-lint-action@v3
+        with:
+          version: v1.51
diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
@@ -1,12 +1,6 @@
 #
 # Automatically tag a merge with master, or build a new image from the tag.
 #
-# Secrets required:
-#  * `DO_TOKEN` - DigitalOcean private token
-#  * `DO_REGISTRY_NAME` - DigitalOcean name of the registry
-#  * `GO_MOD_USER` - Machine username to read private repos
-#  * `GO_MOD_PASS` - Machine password to read private repos
-#
 
 name: Release
 
@@ -23,13 +17,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
         with:
           fetch-depth: "0" # make sure we get all commits!
 
       - name: Bump version and push tag
         id: bump
-        uses: anothrNick/github-tag-action@1.36.0
+        uses: anothrNick/github-tag-action@1.52.0
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           RELEASE_BRANCHES: release

diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml
@@ -6,19 +6,19 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - name: Set up Go
-      uses: actions/setup-go@v1
-      with:
-        go-version: '1.16.2'
-      id: go
+      - name: Set up Go
+        uses: actions/setup-go@v1
+        with:
+          go-version: "1.18"
+        id: go
 
-    - name: Check out code
-      uses: actions/checkout@v2
+      - name: Check out code
+        uses: actions/checkout@v2
 
-    - name: Install Dependencies
-      env:
-        GOPROXY: https://proxy.golang.org,direct
-      run: go mod download
+      - name: Install Dependencies
+        env:
+          GOPROXY: https://proxy.golang.org,direct
+        run: go mod download
 
-    - name: Test
-      run: go test -tags unit -race ./...
+      - name: Test
+        run: go test -tags unit -race ./...
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,2 @@
+vendor/
+.idea/
diff --git a/.golangci.yml b/.golangci.yml
@@ -11,50 +11,26 @@ output:
   print-issued-lines: false
 
 linters:
-  enable-all: true
-  disable:
-    - maligned
-    - megacheck
-    - lll
-    - typecheck # `go build` catches this, and it doesn't currently work with Go 1.11 modules
-    - goimports # horrendously slow with go modules :(
-    - dupl # has never been actually useful
-    - gochecknoglobals
-    - gochecknoinits
-    - interfacer # author deprecated it because it provides bad suggestions
-    - funlen
-    - whitespace
-    - godox
-    - wsl
-    - dogsled
-    - gomnd
-    - gocognit
+  enable:
     - gocyclo
-    - scopelint
-    - godot
-    - nestif
-    - testpackage
-    - goerr113
-    - gci
-    - gofumpt
-    - exhaustivestruct
-    - nlreturn
-    - forbidigo
-    - cyclop
-    - paralleltest
-    - ifshort # so annoying
-    - golint
-    - tagliatelle
-    - forcetypeassert
-    - wrapcheck
+    - gocritic
+    - goconst
+    - dupl
+    - unconvert
+    - goimports
+    - unused
+    - vetshadow
+    - nakedret
+    - errcheck
     - revive
-    - structcheck
-    - stylecheck
-    - exhaustive
-    - varnamelen
+    - ineffassign
+    - goconst
+    - vet
+    - unparam
+    - gofmt
 
 linters-settings:
-  govet:
+  vet:
     check-shadowing: true
     use-installed-packages: true
   dupl:
@@ -67,23 +43,28 @@ linters-settings:
   gocritic:
     disabled-checks:
       - ifElseChain
-
+  gofmt:
+    rewrite-rules:
+    - pattern:     'interface{}'
+      replacement: 'any'
+    - pattern:     'a[b:len(a)]'
+      replacement: 'a[b:]'
 
 issues:
   max-per-linter: 0
   max-same: 0
   exclude-use-default: false
   exclude:
     # Captured by errcheck.
-    - '^(G104|G204):'
+    - "^(G104|G204):"
     # Very commonly not checked.
     - 'Error return value of .(.*\.Help|.*\.MarkFlagRequired|(os\.)?std(out|err)\..*|.*Close|.*Flush|os\.Remove(All)?|.*Print(f|ln|)|os\.(Un)?Setenv). is not checked'
     # Weird error only seen on Kochiku...
-    - 'internal error: no range for'
+    - "internal error: no range for"
     - 'exported method `.*\.(MarshalJSON|UnmarshalJSON|URN|Payload|GoString|Close|Provides|Requires|ExcludeFromHash|MarshalText|UnmarshalText|Description|Check|Poll|Severity)` should have comment or be unexported'
-    - 'composite literal uses unkeyed fields'
+    - "composite literal uses unkeyed fields"
     - 'declaration of "err" shadows declaration'
-    - 'by other packages, and that stutters'
-    - 'Potential file inclusion via variable'
-    - 'at least one file in a package should have a package comment'
-    - 'bad syntax for struct tag pair'
+    - "by other packages, and that stutters"
+    - "Potential file inclusion via variable"
+    - "at least one file in a package should have a package comment"
+    - "bad syntax for struct tag pair"
diff --git a/README.md b/README.md
@@ -22,7 +22,9 @@ This repository is a fork of the original [jsonschema](https://github.com/alecth
 
 ## Versions
 
-This project is still under v0 scheme, as per Go convention, breaking changes are likely. Please pin go modules to branches, and reach out if you think something can be improved.
+This project is still under v0 scheme, as per Go convention, breaking changes are likely. Please pin go modules to version tags or branches, and reach out if you think something can be improved.
+
+Go version >= 1.18 is required as generics are now being used.
 
 ## Example
 
@@ -49,7 +51,8 @@ jsonschema.Reflect(&TestUser{})
 
 ```json
 {
-  "$schema": "http://json-schema.org/draft/2020-12/schema",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/invopop/jsonschema_test/sample-user",
   "$ref": "#/$defs/SampleUser",
   "$defs": {
     "SampleUser": {
@@ -301,7 +304,14 @@ As you can see, if a field name has a `json:""` tag set, the `key` argument to `
 
 Sometimes it can be useful to have custom JSON Marshal and Unmarshal methods in your structs that automatically convert for example a string into an object.
 
-To override auto-generating an object type for your type, implement the `JSONSchema() *Schema` method and whatever is defined will be provided in the schema definitions.
+This library will recognize and attempt to call four different methods that help you adjust schemas to your specific needs:
+
+- `JSONSchema() *Schema` - will prevent auto-generation of the schema so that you can provide your own definition.
+- `JSONSchemaExtend(schema *jsonschema.Schema)` - will be called _after_ the schema has been generated, allowing you to add or manipulate the fields easily.
+- `JSONSchemaAlias() any` - is called when reflecting the type of object and allows for an alternative to be used instead.
+- `JSONSchemaProperty(prop string) any` - will be called for every property inside a struct giving you the chance to provide an alternative object to convert into a schema.
+
+Note that all of these methods **must** be defined on a non-pointer object for them to be called.
 
 Take the following simplified example of a `CompactDate` that only includes the Year and Month:
 

diff --git a/comment_extractor.go b/comment_extractor.go
@@ -22,7 +22,11 @@ func handleType(expr ast.Expr, breadcrumb string, comments map[string]string) {
 				}
 
 				b := fmt.Sprintf("%s.%s", breadcrumb, name.Name)
-				comments[b] = strings.TrimSpace(field.Doc.Text())
+				txt := field.Doc.Text()
+				if txt == "" {
+					txt = field.Comment.Text()
+				}
+				comments[b] = strings.TrimSpace(txt)
 				handleType(field.Type, b, comments)
 			}
 		}

diff --git a/examples/nested/nested.go b/examples/nested/nested.go
@@ -16,6 +16,8 @@ type (
 	// Plant represents the plants the user might have and serves as a test
 	// of structs inside a `type` set.
 	Plant struct {
-		Variant string `json:"variant" jsonschema:"title=Variant"` // This comment will be ignored
+		Variant string `json:"variant" jsonschema:"title=Variant"` // This comment will be used
+		// Multicellular is true if the plant is multicellular
+		Multicellular bool `json:"multicellular,omitempty" jsonschema:"title=Multicellular"` // This comment will be ignored
 	}
 )
diff --git a/examples/user.go b/examples/user.go
@@ -17,7 +17,7 @@ type User struct {
 		// A note about this friend
 		FriendNote string `json:"friend_note,omitempty"`
 	} `json:"friends,omitempty" jsonschema_description:"list of friends, omitted when empty"`
-	Tags map[string]interface{} `json:"tags,omitempty"`
+	Tags map[string]any `json:"tags,omitempty"`
 
 	// An array of pets the user cares for.
 	Pets nested.Pets `json:"pets"`

diff --git a/examples_test.go b/examples_test.go
@@ -9,14 +9,14 @@ import (
 )
 
 type SampleUser struct {
-	ID          int                    `json:"id"`
-	Name        string                 `json:"name" jsonschema:"title=the name,description=The name of a friend,example=joe,example=lucy,default=alex"`
-	Friends     []int                  `json:"friends,omitempty" jsonschema_description:"The list of IDs, omitted when empty"`
-	Tags        map[string]interface{} `json:"tags,omitempty" jsonschema_extras:"a=b,foo=bar,foo=bar1"`
-	BirthDate   time.Time              `json:"birth_date,omitempty" jsonschema:"oneof_required=date"`
-	YearOfBirth string                 `json:"year_of_birth,omitempty" jsonschema:"oneof_required=year"`
-	Metadata    interface{}            `json:"metadata,omitempty" jsonschema:"oneof_type=string;array"`
-	FavColor    string                 `json:"fav_color,omitempty" jsonschema:"enum=red,enum=green,enum=blue"`
+	ID          int            `json:"id"`
+	Name        string         `json:"name" jsonschema:"title=the name,description=The name of a friend,example=joe,example=lucy,default=alex"`
+	Friends     []int          `json:"friends,omitempty" jsonschema_description:"The list of IDs, omitted when empty"`
+	Tags        map[string]any `json:"tags,omitempty" jsonschema_extras:"a=b,foo=bar,foo=bar1"`
+	BirthDate   time.Time      `json:"birth_date,omitempty" jsonschema:"oneof_required=date"`
+	YearOfBirth string         `json:"year_of_birth,omitempty" jsonschema:"oneof_required=year"`
+	Metadata    any            `json:"metadata,omitempty" jsonschema:"oneof_type=string;array"`
+	FavColor    string         `json:"fav_color,omitempty" jsonschema:"enum=red,enum=green,enum=blue"`
 }
 
 func ExampleReflect() {

diff --git a/fixtures/allow_additional_props.json b/fixtures/allow_additional_props.json
@@ -67,10 +67,8 @@
           "description": "list of IDs, omitted when empty"
         },
         "tags": {
-          "patternProperties": {
-            ".*": {
-              "type": "string"
-            }
+          "additionalProperties": {
+            "type": "string"
           },
           "type": "object"
         },
@@ -120,9 +118,9 @@
         "age": {
           "type": "integer",
           "maximum": 120,
-          "exclusiveMaximum": true,
+          "exclusiveMaximum": 121,
           "minimum": 18,
-          "exclusiveMinimum": true
+          "exclusiveMinimum": 17
         },
         "email": {
           "type": "string",
@@ -140,6 +138,11 @@
           ],
           "hello": "world"
         },
+        "bool_extra": {
+          "type": "string",
+          "isFalse": false,
+          "isTrue": true
+        },
         "color": {
           "type": "string",
           "enum": [
@@ -159,9 +162,9 @@
         "mult": {
           "type": "number",
           "enum": [
-            1,
+            1.0,
             1.5,
-            2
+            2.0
           ]
         },
         "roles": {
@@ -211,6 +214,8 @@
         "name",
         "password",
         "TestFlag",
+        "photo",
+        "photo2",
         "age",
         "email",
         "uuid",