Fix lint, add docs

Makefile

@@ -50,5 +50,5 @@ gen-3.0:
 ## Generate entities from schema
 gen-3.1:
 	@test -s $(GOPATH)/bin/json-cli-$(JSON_CLI_VERSION_31) || (curl -sSfL https://github.com/swaggest/json-cli/releases/download/$(JSON_CLI_VERSION_31)/json-cli -o $(GOPATH)/bin/json-cli-$(JSON_CLI_VERSION_31) && chmod +x $(GOPATH)/bin/json-cli-$(JSON_CLI_VERSION_31))
-	@cd resources/schema/ && $(GOPATH)/bin/json-cli-$(JSON_CLI_VERSION_31)  gen-go openapi31-patched.json --output ../../openapi31/entities.go --package-name openapi31 --def-ptr '#/$$defs' --with-zero-values --validate-required --fluent-setters --root-name Spec
+	@cd resources/schema/ && $(GOPATH)/bin/json-cli-$(JSON_CLI_VERSION_31)  gen-go openapi31-patched.json --config openapi31-config.json --output ../../openapi31/entities.go --package-name openapi31 --def-ptr '#/$$defs' --with-zero-values --validate-required --fluent-setters --root-name Spec
 	@gofmt -w ./openapi31/entities.go

README.md

@@ -16,7 +16,7 @@ For automated HTTP REST service framework built with this library please check [
 ## Features
 
 * Type safe mapping of OpenAPI 3 documents with Go structures generated from schema.
-* Type-based reflection of Go structures to OpenAPI 3 schema.
+* Type-based reflection of Go structures to OpenAPI 3.0 or 3.1 schema.
 * Schema control with field tags
     * `json` for request bodies and responses in JSON
     * `query`, `path` for parameters in URL

openapi3/example_test.go

@@ -6,6 +6,7 @@ import (
 	"net/http"
 	"time"
 
+	"github.com/swaggest/openapi-go"
 	"github.com/swaggest/openapi-go/openapi3"
 )
 
@@ -339,8 +340,8 @@ components:
 	// bar
 }
 
-func ExampleReflector_SetJSONResponse() {
-	reflector := openapi3.Reflector{}
+func ExampleReflector_AddOperation() {
+	reflector := openapi3.NewReflector()
 	reflector.Spec = &openapi3.Spec{Openapi: "3.0.3"}
 	reflector.Spec.Info.
 		WithTitle("Things API").
@@ -368,18 +369,17 @@ func ExampleReflector_SetJSONResponse() {
 		UpdatedAt time.Time `json:"updated_at"`
 	}
 
-	putOp := openapi3.Operation{}
+	putOp, _ := reflector.NewOperationContext(http.MethodPut, "/things/{id}")
 
-	handleError(reflector.SetRequest(&putOp, new(req), http.MethodPut))
-	handleError(reflector.SetJSONResponse(&putOp, new(resp), http.StatusOK))
-	handleError(reflector.SetJSONResponse(&putOp, new([]resp), http.StatusConflict))
-	handleError(reflector.Spec.AddOperation(http.MethodPut, "/things/{id}", putOp))
+	putOp.AddReqStructure(new(req))
+	putOp.AddRespStructure(new(resp))
+	putOp.AddRespStructure(new([]resp), openapi.WithHTTPStatus(http.StatusConflict))
+	handleError(reflector.AddOperation(putOp))
 
-	getOp := openapi3.Operation{}
-
-	handleError(reflector.SetRequest(&getOp, new(req), http.MethodGet))
-	handleError(reflector.SetJSONResponse(&getOp, new(resp), http.StatusOK))
-	handleError(reflector.Spec.AddOperation(http.MethodGet, "/things/{id}", getOp))
+	getOp, _ := reflector.NewOperationContext(http.MethodGet, "/things/{id}")
+	getOp.AddReqStructure(new(req))
+	getOp.AddRespStructure(new(resp))
+	handleError(reflector.AddOperation(getOp))
 
 	schema, err := reflector.Spec.MarshalYAML()
 	if err != nil {
@@ -493,9 +493,8 @@ func ExampleReflector_SetJSONResponse() {
 	//       type: object
 }
 
-func ExampleReflector_SetRequest_queryObject() {
-	reflector := openapi3.Reflector{}
-	reflector.Spec = &openapi3.Spec{Openapi: "3.0.3"}
+func ExampleReflector_AddOperation_queryObject() {
+	reflector := openapi3.NewReflector()
 	reflector.Spec.Info.
 		WithTitle("Things API").
 		WithVersion("1.2.3").
@@ -526,10 +525,10 @@ func ExampleReflector_SetRequest_queryObject() {
 		DeepObjectFilter deepObjectFilter `query:"deep_object_filter"`
 	}
 
-	getOp := openapi3.Operation{}
+	getOp, _ := reflector.NewOperationContext(http.MethodGet, "/things/{id}")
 
-	_ = reflector.SetRequest(&getOp, new(req), http.MethodGet)
-	_ = reflector.Spec.AddOperation(http.MethodGet, "/things/{id}", getOp)
+	getOp.AddReqStructure(new(req))
+	_ = reflector.AddOperation(getOp)
 
 	schema, err := reflector.Spec.MarshalYAML()
 	if err != nil {

openapi3/jsonschema.go

@@ -25,7 +25,7 @@ func (s *SchemaOrRef) ToJSONSchema(spec *Spec) jsonschema.SchemaOrBool {
 
 	// Inline root reference without recursions.
 	if s.SchemaReference != nil {
-		dstName := strings.TrimPrefix(s.SchemaReference.Ref, "#/components/schemas/")
+		dstName := strings.TrimPrefix(s.SchemaReference.Ref, componentsSchemas)
 		if ctx.refsCount[dstName] == 1 {
 			js = ctx.refsProcessed[dstName]
 			delete(ctx.refsProcessed, dstName)
@@ -49,8 +49,8 @@ func (s *SchemaOrRef) toJSONSchema(ctx toJSONSchemaContext) jsonschema.SchemaOrB
 	if s.SchemaReference != nil {
 		jso.WithRef(s.SchemaReference.Ref)
 
-		if strings.HasPrefix(s.SchemaReference.Ref, "#/components/schemas/") {
-			dstName := strings.TrimPrefix(s.SchemaReference.Ref, "#/components/schemas/")
+		if strings.HasPrefix(s.SchemaReference.Ref, componentsSchemas) {
+			dstName := strings.TrimPrefix(s.SchemaReference.Ref, componentsSchemas)
 
 			if _, alreadyProcessed := ctx.refsProcessed[dstName]; !alreadyProcessed {
 				ctx.refsProcessed[dstName] = jsonschema.SchemaOrBool{}

openapi31/doc.go

@@ -0,0 +1,6 @@
+// Package openapi31 provides entities and helpers to manage OpenAPI 3.1.x schema.
+//
+// PLEASE NOTE: this package is currently experimental and may have backwards incompatible API changes in near future.
+// API would be considered stable, once this disclaimer is removed.
+// Give it a try and file issues if you face any.
+package openapi31