Skip to content

Commit c9809a6

Browse files
fredbiclaude
fredbi
and
claude
authored
docs: add FAQ from resolved GitHub issues (#403)
Extract answers to common questions from 13 open issues tagged "question" into docs/FAQ.md, covering client usage (TLS, content types, error handling), middleware (auth, context, validation), and Swagger UI configuration. Link the FAQ from README.md. Closes #31 Closes #44 Closes #82 Closes #89 Closes #121 Closes #196 Closes #201 Closes #203 Closes #252 Closes #253 Closes #316 Closes #329 Closes #375 Signed-off-by: Frederic BIDON <fredbi@yahoo.com> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 3d599d6 commit c9809a6

2 files changed

Lines changed: 157 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@ on top of which it has been built.
6262

6363
## Other documentation
6464

65+
* [FAQ](docs/FAQ.md)
6566
* [All-time contributors](./CONTRIBUTORS.md)
6667
* [Contributing guidelines](.github/CONTRIBUTING.md)
6768
* [Maintainers documentation](docs/MAINTAINERS.md)

‎docs/FAQ.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# Frequently Asked Questions
2+
3+
Answers to common questions collected from [GitHub issues](https://github.com/go-openapi/runtime/issues).
4+
5+
---
6+
7+
## Client
8+
9+
### How do I disable TLS certificate verification?
10+
11+
Use `TLSClientOptions` with `InsecureSkipVerify`:
12+
13+
```go
14+
import "github.com/go-openapi/runtime/client"
15+
16+
httpClient, err := client.TLSClient(client.TLSClientOptions{
17+
InsecureSkipVerify: true,
18+
})
19+
```
20+
21+
Then pass the resulting `*http.Client` to your transport.
22+
23+
> [#196](https://github.com/go-openapi/runtime/issues/196)
24+
25+
### Why is `request.ContentLength` zero when I send a body?
26+
27+
A streaming body (e.g. from `bytes.NewReader`) is sent with chunked transfer encoding.
28+
The runtime cannot know the content length of an arbitrary stream unless you explicitly
29+
set it on the request. If you need `ContentLength` populated, set it yourself before
30+
submitting.
31+
32+
> [#253](https://github.com/go-openapi/runtime/issues/253)
33+
34+
### How do I read the error response body from an `APIError`?
35+
36+
The client's `Submit()` closes the response body after reading. To access error details,
37+
define your error responses (including a `default` response) in the Swagger spec with a
38+
schema. The generated client will then deserialize the error body into a typed struct
39+
that you can access via type assertion:
40+
41+
```go
42+
if apiErr, ok := err.(*mypackage.GetThingDefault); ok {
43+
// apiErr.Payload contains the deserialized error body
44+
}
45+
```
46+
47+
Without a response schema in the spec, the body is discarded and only the status code
48+
is available in the `runtime.APIError`.
49+
50+
> [#89](https://github.com/go-openapi/runtime/issues/89), [#121](https://github.com/go-openapi/runtime/issues/121)
51+
52+
### How do I register custom MIME types (e.g. `application/problem+json`)?
53+
54+
The default client runtime ships with a fixed set of consumers/producers. Register
55+
custom ones on the transport:
56+
57+
```go
58+
rt := client.New(host, basePath, schemes)
59+
rt.Consumers["application/problem+json"] = runtime.JSONConsumer()
60+
rt.Producers["application/problem+json"] = runtime.JSONProducer()
61+
```
62+
63+
The same approach works for any non-standard MIME type such as `application/pdf`
64+
(use `runtime.ByteStreamConsumer()`), `application/hal+json`, or
65+
`application/vnd.error+json` (use `runtime.JSONConsumer()`).
66+
67+
> [#31](https://github.com/go-openapi/runtime/issues/31), [#252](https://github.com/go-openapi/runtime/issues/252), [#329](https://github.com/go-openapi/runtime/issues/329)
68+
69+
---
70+
71+
## Middleware
72+
73+
### How do I access the authenticated Principal from an `OperationHandler`?
74+
75+
Use the context helpers from the `middleware` package:
76+
77+
```go
78+
func myHandler(r *http.Request, params MyParams) middleware.Responder {
79+
principal := middleware.SecurityPrincipalFrom(r)
80+
route := middleware.MatchedRouteFrom(r)
81+
scopes := middleware.SecurityScopesFrom(r)
82+
// ...
83+
}
84+
```
85+
86+
These extract values that the middleware pipeline stored in the request context
87+
during authentication and routing.
88+
89+
> [#203](https://github.com/go-openapi/runtime/issues/203)
90+
91+
### Can I run authentication on requests that don't match a route?
92+
93+
No. Authentication is determined dynamically per route from the OpenAPI spec
94+
(each operation declares its own security requirements). The middleware pipeline
95+
authenticates *after* routing, so unmatched requests are never authenticated.
96+
97+
> [#201](https://github.com/go-openapi/runtime/issues/201)
98+
99+
### How do I share context values across middlewares when using an external router?
100+
101+
The go-openapi router creates a new request context during route resolution.
102+
Context values set after routing (e.g. during auth) are not visible to middlewares
103+
that run before the router in the chain.
104+
105+
The recommended pattern is to use a pointer-based shared struct:
106+
107+
```go
108+
type sharedCtx struct {
109+
Principal any
110+
// add fields as needed
111+
}
112+
113+
// In your outermost middleware, before the router:
114+
sc := &sharedCtx{}
115+
ctx := context.WithValue(r.Context(), sharedCtxKey, sc)
116+
next.ServeHTTP(w, r.WithContext(ctx))
117+
// After ServeHTTP returns, sc is populated by inner middlewares.
118+
119+
// In an inner middleware or auth handler:
120+
sc := r.Context().Value(sharedCtxKey).(*sharedCtx)
121+
sc.Principal = principal // visible to the outer middleware
122+
```
123+
124+
Because the struct is shared by pointer, mutations are visible regardless of
125+
which request copy carries the context.
126+
127+
> [#375](https://github.com/go-openapi/runtime/issues/375)
128+
129+
### Can I use this library to validate requests/responses without code generation?
130+
131+
Yes. Use the routing and validation middleware from the `middleware` package with
132+
an untyped API. Load your spec with `loads.Spec()`, then wire up
133+
`middleware.NewRouter()` to get request validation against the spec without
134+
needing go-swagger generated code. See the `middleware/untyped` package for
135+
examples.
136+
137+
> [#44](https://github.com/go-openapi/runtime/issues/44)
138+
139+
### How do I configure Swagger UI to show multiple specs?
140+
141+
`SwaggerUIOpts` supports the `urls` parameter for listing multiple spec files in
142+
the Swagger UI explore bar. Configure it instead of the single `url` parameter.
143+
144+
> [#316](https://github.com/go-openapi/runtime/issues/316)
145+
146+
---
147+
148+
## Documentation
149+
150+
### Where can I find middleware documentation?
151+
152+
- [GoDoc](https://pkg.go.dev/github.com/go-openapi/runtime/middleware) — API reference
153+
- [go-swagger middleware guide](https://goswagger.io/use/middleware.html) — usage patterns
154+
- [go-swagger FAQ](https://goswagger.io/faq/) — common questions
155+
156+
> [#82](https://github.com/go-openapi/runtime/issues/82)

0 commit comments

Comments
 (0)