Skip to content

Commit

Permalink
Update deps, add more usage examples (#183)
Browse files Browse the repository at this point in the history
  • Loading branch information
@vearutop
vearutop committed Oct 30, 2023
1 parent 8d8c0d6 commit 62a510e
Show file tree
Hide file tree
Showing 11 changed files with 571 additions and 72 deletions.
167 changes: 150 additions & 17 deletions _examples/advanced-generic-openapi31/_testdata/openapi.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,12 @@
"info":{"title":"Advanced Example","description":"This app showcases a variety of features.","version":"v1.2.3"},
"paths":{
"/deeper-with-session/one":{
"parameters":[
{
"name":"X-Umbrella-Header","in":"header","description":"This request header is supported in all operations.",
"schema":{"type":"string"}
}
],
"get":{
"tags":["Other"],"summary":"Dummy","operationId":"_examples/advanced-generic-openapi31.dummy2",
"responses":{
Expand All @@ -16,6 +22,12 @@
}
},
"/deeper-with-session/two":{
"parameters":[
{
"name":"X-Umbrella-Header","in":"header","description":"This request header is supported in all operations.",
"schema":{"type":"string"}
}
],
"get":{
"tags":["Other"],"summary":"Dummy","operationId":"_examples/advanced-generic-openapi31.dummy3",
"responses":{
Expand All @@ -29,6 +41,12 @@
}
},
"/error-response":{
"parameters":[
{
"name":"X-Umbrella-Header","in":"header","description":"This request header is supported in all operations.",
"schema":{"type":"string"}
}
],
"get":{
"tags":["Response"],"summary":"Declare Expected Errors",
"description":"This use case demonstrates documentation of expected errors.",
Expand Down Expand Up @@ -69,6 +87,12 @@
}
},
"/file-multi-upload":{
"parameters":[
{
"name":"X-Umbrella-Header","in":"header","description":"This request header is supported in all operations.",
"schema":{"type":"string"}
}
],
"post":{
"tags":["Request"],"summary":"Files Uploads With 'multipart/form-data'",
"operationId":"_examples/advanced-generic-openapi31.fileMultiUploader",
Expand All @@ -89,6 +113,12 @@
}
},
"/file-upload":{
"parameters":[
{
"name":"X-Umbrella-Header","in":"header","description":"This request header is supported in all operations.",
"schema":{"type":"string"}
}
],
"post":{
"tags":["Request"],"summary":"File Upload With 'multipart/form-data'",
"operationId":"_examples/advanced-generic-openapi31.fileUploader",
Expand All @@ -106,6 +136,12 @@
}
},
"/form":{
"parameters":[
{
"name":"X-Umbrella-Header","in":"header","description":"This request header is supported in all operations.",
"schema":{"type":"string"}
}
],
"post":{
"tags":["Request"],"summary":"Request With Form",
"description":"The `form` field tag acts as `query` and `formData`, with priority on `formData`.\n\nIt is decoded with `http.Request.Form` values.",
Expand All @@ -126,6 +162,12 @@
}
},
"/gzip-pass-through":{
"parameters":[
{
"name":"X-Umbrella-Header","in":"header","description":"This request header is supported in all operations.",
"schema":{"type":"string"}
}
],
"get":{
"tags":["Response"],"summary":"Direct Gzip","operationId":"_examples/advanced-generic-openapi31.directGzip",
"parameters":[
Expand Down Expand Up @@ -163,6 +205,12 @@
}
},
"/html-response/{id}":{
"parameters":[
{
"name":"X-Umbrella-Header","in":"header","description":"This request header is supported in all operations.",
"schema":{"type":"string"}
}
],
"get":{
"tags":["Response"],"summary":"Request With HTML Response",
"description":"Request with templated HTML response.",
Expand All @@ -182,6 +230,12 @@
}
},
"/json-body-manual/{in-path}":{
"parameters":[
{
"name":"X-Umbrella-Header","in":"header","description":"This request header is supported in all operations.",
"schema":{"type":"string"}
}
],
"post":{
"tags":["Request"],"summary":"Request With JSON Body and manual decoder",
"description":"Request with JSON body and query/header/path params, response with JSON body and data from request.",
Expand Down Expand Up @@ -211,6 +265,12 @@
}
},
"/json-body-validation/{in-path}":{
"parameters":[
{
"name":"X-Umbrella-Header","in":"header","description":"This request header is supported in all operations.",
"schema":{"type":"string"}
}
],
"post":{
"tags":["Request","Response","Validation"],"summary":"Request With JSON Body and non-trivial validation",
"description":"Request with JSON body and query/header/path params, response with JSON body and data from request.",
Expand Down Expand Up @@ -240,6 +300,12 @@
}
},
"/json-body/{in-path}":{
"parameters":[
{
"name":"X-Umbrella-Header","in":"header","description":"This request header is supported in all operations.",
"schema":{"type":"string"}
}
],
"post":{
"tags":["Request"],"summary":"Request With JSON Body",
"description":"Request with JSON body and query/header/path params, response with JSON body and data from request.",
Expand Down Expand Up @@ -269,6 +335,12 @@
}
},
"/json-map-body":{
"parameters":[
{
"name":"X-Umbrella-Header","in":"header","description":"This request header is supported in all operations.",
"schema":{"type":"string"}
}
],
"post":{
"tags":["Request"],"summary":"Request With JSON Map In Body",
"description":"Request with JSON object (map) body.",
Expand All @@ -294,6 +366,12 @@
}
},
"/json-param/{in-path}":{
"parameters":[
{
"name":"X-Umbrella-Header","in":"header","description":"This request header is supported in all operations.",
"schema":{"type":"string"}
}
],
"get":{
"tags":["Request"],"summary":"Request With JSON Query Parameter",
"description":"Request with JSON body and query/header/path params, response with JSON body and data from request.",
Expand Down Expand Up @@ -330,6 +408,12 @@
}
},
"/json-slice-body":{
"parameters":[
{
"name":"X-Umbrella-Header","in":"header","description":"This request header is supported in all operations.",
"schema":{"type":"string"}
}
],
"post":{
"tags":["Request"],"summary":"Request With JSON Array In Body",
"operationId":"_examples/advanced-generic-openapi31.jsonSliceBody",
Expand All @@ -354,6 +438,12 @@
}
},
"/no-validation":{
"parameters":[
{
"name":"X-Umbrella-Header","in":"header","description":"This request header is supported in all operations.",
"schema":{"type":"string"}
}
],
"post":{
"tags":["Request","Response"],"summary":"No Validation","description":"Input/Output without validation.",
"operationId":"_examples/advanced-generic-openapi31.noValidation",
Expand All @@ -376,6 +466,12 @@
}
},
"/output-csv-writer":{
"parameters":[
{
"name":"X-Umbrella-Header","in":"header","description":"This request header is supported in all operations.",
"schema":{"type":"string"}
}
],
"get":{
"tags":["Response"],"summary":"Output With Stream Writer","description":"Output with stream writer.",
"operationId":"_examples/advanced-generic-openapi31.outputCSVWriter",
Expand Down Expand Up @@ -408,6 +504,12 @@
}
},
"/output-headers":{
"parameters":[
{
"name":"X-Umbrella-Header","in":"header","description":"This request header is supported in all operations.",
"schema":{"type":"string"}
}
],
"get":{
"tags":["Response"],"summary":"Output With Headers","description":"Output with headers.",
"operationId":"_examples/advanced-generic-openapi31.outputHeaders",
Expand Down Expand Up @@ -474,6 +576,12 @@
}
},
"/query-object":{
"parameters":[
{
"name":"X-Umbrella-Header","in":"header","description":"This request header is supported in all operations.",
"schema":{"type":"string"}
}
],
"get":{
"tags":["Request"],"summary":"Request With Object As Query Parameter",
"operationId":"_examples/advanced-generic-openapi31.queryObject",
Expand Down Expand Up @@ -505,6 +613,12 @@
}
},
"/req-resp-mapping":{
"parameters":[
{
"name":"X-Umbrella-Header","in":"header","description":"This request header is supported in all operations.",
"schema":{"type":"string"}
}
],
"post":{
"tags":["Request","Response"],"summary":"Request Response Mapping",
"description":"This use case has transport concerns fully decoupled with external req/resp mapping.",
Expand All @@ -515,9 +629,7 @@
"schema":{"description":"Simple scalar value with sample validation.","minLength":3,"type":"string"}
}
],
"requestBody":{
"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/FormDataAdvancedInputPort"}}}
},
"requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/AdvancedInputPort"}}}},
"responses":{
"204":{
"description":"No Content",
Expand All @@ -536,6 +648,12 @@
}
},
"/root-with-session":{
"parameters":[
{
"name":"X-Umbrella-Header","in":"header","description":"This request header is supported in all operations.",
"schema":{"type":"string"}
}
],
"get":{
"tags":["Other"],"summary":"Dummy","operationId":"_examples/advanced-generic-openapi31.dummy",
"responses":{
Expand All @@ -549,6 +667,12 @@
}
},
"/text-req-body-ptr/{path}":{
"parameters":[
{
"name":"X-Umbrella-Header","in":"header","description":"This request header is supported in all operations.",
"schema":{"type":"string"}
}
],
"post":{
"tags":["Request"],"summary":"Request With Text Body (ptr input)",
"description":"This usecase allows direct access to original `*http.Request` while keeping automated decoding of parameters.",
Expand All @@ -568,6 +692,12 @@
}
},
"/text-req-body/{path}":{
"parameters":[
{
"name":"X-Umbrella-Header","in":"header","description":"This request header is supported in all operations.",
"schema":{"type":"string"}
}
],
"post":{
"tags":["Request"],"summary":"Request With Text Body",
"description":"This usecase allows direct access to original `*http.Request` while keeping automated decoding of parameters.",
Expand All @@ -587,6 +717,12 @@
}
},
"/validation":{
"parameters":[
{
"name":"X-Umbrella-Header","in":"header","description":"This request header is supported in all operations.",
"schema":{"type":"string"}
}
],
"post":{
"tags":["Request","Response","Validation"],"summary":"Validation",
"description":"Input/Output with validation. Custom annotation.",
Expand Down Expand Up @@ -654,6 +790,11 @@
},
"type":"object"
},
"AdvancedInputPort":{
"additionalProperties":false,
"properties":{"val2":{"description":"Simple scalar value with sample validation.","minimum":3,"type":"integer"}},
"required":["val2"],"type":"object"
},
"AdvancedInputPortType2":{
"additionalProperties":false,
"properties":{
Expand Down Expand Up @@ -759,20 +900,12 @@
"type":"object"
},
"FormDataAdvancedForm":{"additionalProperties":false,"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object"},
"FormDataAdvancedInputPort":{
"additionalProperties":false,
"properties":{"val2":{"description":"Simple scalar value with sample validation.","minimum":3,"type":"integer"}},
"required":["val2"],"type":"object"
},
"FormDataAdvancedUpload":{
"additionalProperties":false,
"properties":{
"simple":{"description":"Simple scalar value in body.","type":"string"},
"upload1":{
"$ref":"#/components/schemas/FormDataMultipartFileHeader",
"description":"Upload with *multipart.FileHeader."
},
"upload2":{"$ref":"#/components/schemas/FormDataMultipartFile","description":"Upload with multipart.File."}
"upload1":{"$ref":"#/components/schemas/MultipartFileHeader","description":"Upload with *multipart.FileHeader."},
"upload2":{"$ref":"#/components/schemas/MultipartFile","description":"Upload with multipart.File."}
},
"type":"object"
},
Expand All @@ -782,17 +915,17 @@
"simple":{"description":"Simple scalar value in body.","type":"string"},
"uploads1":{
"description":"Uploads with *multipart.FileHeader.",
"items":{"$ref":"#/components/schemas/FormDataMultipartFileHeader"},"type":["array","null"]
"items":{"$ref":"#/components/schemas/MultipartFileHeader"},"type":["array","null"]
},
"uploads2":{
"description":"Uploads with multipart.File.","items":{"$ref":"#/components/schemas/FormDataMultipartFile"},
"description":"Uploads with multipart.File.","items":{"$ref":"#/components/schemas/MultipartFile"},
"type":["array","null"]
}
},
"type":"object"
},
"FormDataMultipartFile":{"format":"binary","type":["null","string"]},
"FormDataMultipartFileHeader":{"format":"binary","type":["null","string"]},
"MultipartFile":{"format":"binary","type":["null","string"]},
"MultipartFileHeader":{"format":"binary","type":["null","string"]},
"RestErrResponse":{
"properties":{
"code":{"description":"Application-specific error code.","type":"integer"},
Expand Down
18 changes: 17 additions & 1 deletion _examples/advanced-generic-openapi31/router.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,8 @@ import (
)

func NewRouter() http.Handler {
s := web.NewService(openapi31.NewReflector())
r := openapi31.NewReflector()
s := web.NewService(r)

s.OpenAPISchema().SetTitle("Advanced Example")
s.OpenAPISchema().SetDescription("This app showcases a variety of features.")
Expand Down Expand Up @@ -231,6 +232,21 @@ func NewRouter() http.Handler {
})
})

// You can also walk the spec and add more information.
for p, pi := range r.Spec.Paths.MapOfPathItemValues {
pi.Parameters = append(pi.Parameters, openapi31.ParameterOrReference{
Parameter: (&openapi31.Parameter{
In: openapi31.ParameterInHeader,
Name: "X-Umbrella-Header",
Schema: map[string]interface{}{
"type": "string",
},
}).WithDescription("This request header is supported in all operations."),
})

r.Spec.Paths.MapOfPathItemValues[p] = pi
}

// Swagger UI endpoint at /docs.
s.Docs("/docs", swgui.New)

Expand Down
Loading

0 comments on commit 62a510e

Please sign in to comment.