FAQ update

Moves issues tagged as questions to FAQ doc site * fixes #1552 * fixes #1501 * fixes #1432 * fixes #1383 * fixes #1381 * fixes #1337 * fixes #1217 * fixes #1205 * fixes #1143 * fixes #1060 * fixes #1022 * fixes #1427 * fixes #1759 * fixes #1517 Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
go-swagger · Dec 21, 2018 · 01cc2f4 · 01cc2f4
1 parent 3099f61
commit 01cc2f4
Show file tree

Hide file tree

Showing 6 changed files with 492 additions and 10 deletions.
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -56,3 +56,4 @@
   - [Spec generation from source](faq/faq_spec.md)
   - [API testing](faq/faq_testing.md)
   - [Documenting your API](faq/faq_documenting.md)
+  - [Swagger specification](faq/faq_swagger.md)
diff --git a/docs/faq/README.md b/docs/faq/README.md
@@ -29,6 +29,12 @@ Feel free to contribute new questions and share your experience with go-swagger!
 * [How to validate dates and times?](faq_model.md#how-to-validate-dates-and-times)
 * [Accessing the return value from Default response](faq_model.md#accessing-the-default-return-value)
 * [How to avoid deep copies of complex data structures that need to be marshalled across the API?](faq_model.md#how-to-avoid-deep-copies-of-complex-data-structures-that-need-to-be-marshalled-across-the-api)
+* [Extra sections in POST body](faq_model.md#extra-sections-in-post-body)
+* [How to support generate type int?](faq_model.md#how-to-support-generate-type-int)
+* [Generate all models necessary for specified operation](faq_model.md#generate-all-models-necessary-for-specified-operation)
+* [Generated code changes the order of properties in struct](faq_model.md#generated-code-changes-the-order-of-properties-in-struct)
+* [Fail to use swagger generate model -name](faq_model.md#fail-to-use-swagger-generate-model-name)
+
 <!-- * How to make custom validators? -->
 
 #### Server generation and customization
@@ -39,6 +45,10 @@ Feel free to contribute new questions and share your experience with go-swagger!
 * [How to access access API struct inside operator handler?](faq_server.md#how-to-access-access-api-struct-inside-operator-handler)
 * [Use go-swagger to generate different client or servers](faq_server.md#use-go-swagger-to-generate-different-client-or-servers)
 * [Support streaming responses](faq_server.md#support-streaming-responses)
+* [OAuth authentication does not redirect to the authorization server](faq_server.md#oauth-authentication-does-not-redirect-to-the-authorization-server)
+* [HTTPS TLS Cipher Suites not supported by AWS Elastic LoadBalancer](faq_server.md#https-tls-cipher-suites-not-supported-by-aws-elastic-loadbalancer)
+* [Which mime types are supported?](faq_server.md#which-mime-types-are-supported)
+* [Is it possible to return error to main function of server?](faq_server.md#is-it-possible-to-return-error-to-main-function-of-server)
 
 #### Client generation
 * [Is there an example for dynamic client?](faq_client.md#example-for-dynamic-client)
@@ -67,6 +77,11 @@ Feel free to contribute new questions and share your experience with go-swagger!
 * [How to use swagger-ui/cors?](faq_server.md#how-to-use-swagger-ui-cors)
 * [Serving my own UI files](faq_server.md#how-to-serve-my-ui-files)
 
+#### Swagger specification
+* [Default vs_required](faq_swagger.md#default-vs-required)
+* [type string, format int64 not respected in generator](faq_swagger.md#type-string-format-int64-not-respected-in-generator)
+* [Duplicate operationId error](faq_swagger.md#duplicate-operationid-error)
+
 <!-- More on that...
 #### Documentation and tutorials
 -->
diff --git a/docs/faq/faq_model.md b/docs/faq/faq_model.md
@@ -6,7 +6,7 @@
 _Use-Case_: is it possible to write my own validation code for custom types? If so, can someone give me an example?
 
 >Usage example:
->There is bookstore, with info about books: author, title, price. 
+>There is bookstore, with info about books: author, title, price.
 > And we want that books from some author will not cost more than some price.
 > So I want to write and use a function ValidateBookCustom() like:
 ```golang
@@ -31,7 +31,7 @@ You might build on that: generating a first model, customizing the validation co
 Another way is to use the `x-go-type extension`, to replace type generation with a custom type.
 
 There is the opportunity to get go-swagger to reuse a predefined type to satisfy the definition in the swagger spec.
-Imported package and type alias may be specified as options, as shown in this example: 
+Imported package and type alias may be specified as options, as shown in this example:
 https://github.com/go-swagger/go-swagger/blob/master/fixtures/codegen/existing-model.yml#L99-L103
 
 That example reuses a type provided by a library with a package alias and type name. The code generator will respect this.
@@ -198,7 +198,7 @@ Originally from issue [#643](https://github.com/go-swagger/go-swagger/issues/643
 ### Accessing the Default return value
 _Use-Case_: I was wondering how I would get the default response from the client?
 
-Note: see also [Access HTTP status code from client#597](https://github.com/go-swagger/go-swagger/issues/597). 
+Note: see also [Access HTTP status code from client#597](https://github.com/go-swagger/go-swagger/issues/597).
 
 I have a spec like this:
 ```YAML
@@ -279,7 +279,7 @@ _Use-Case_:
 
 *How do others deal with this problem?*
 
-- If your question is "How do I write arbitrary response bodies from go-swagger generated server code?" 
+- If your question is "How do I write arbitrary response bodies from go-swagger generated server code?"
   (e.g. from subsystem structs that you have marshalled) then you may want to write your own `middleware.Responder`,
   which gives you direct access to the underlying `http.ResponseWriter`.
   At this point, though, why use go-swagger instead  of a lighter-weight framework?
@@ -313,6 +313,146 @@ https://github.com/go-swagger/go-swagger/blob/master/fixtures/codegen/existing-m
 
 Originally from issue [#948](https://github.com/go-swagger/go-swagger/issues/948).
 
+### Extra sections in POST body
+
+_Use-case_: additional properties in object
+
+If I have a swagger spec that expects
+
+{"foo": 123}
+
+and provide
+
+{"foo": 123, "blah": 345}
+
+it happily goes on about this way.
+
+Two questions:
+1. can I make it complain if extra stuff is included
+2. can I access these extra sections within the go code/handler?
+
+**Answer**: use `additionalProperties: false` or `additionalProperties: true` in your definition.
+when it's set to true you'll have a `map[string]interface{}` added.
+
+Originally from issue [#1337](https://github.com/go-swagger/go-swagger/issues/1337).
+
+### How to support generate type int?
+
+_Use-case_: generating `int` types
+
+> I need to use swagger to generate my modes in go code.
+> But I find I can hardly generate type `int`, always `int64`.
+> Since I need to keep back compatibility for my project, I can hardly change the type.
+> So in this case, does go-swagger meet this requirement?
+
+**Answer**:  int is not a good option to support when it comes to contracts.
+
+> Consider the following: you have an arm32 client on which int is int32, however your server is amd64.
+> At this stage it's perfectly valid for the server to return int32 max value + 1, this will cause the client to overflow.
+> So while go allows int as type I think for API contracts int is too ambiguous as definition leading to subtle but hard to debug failures.
+> Similarly other languages may choose to default to int32 type instead of int64 type regardless of platform.
+
+Originally from issue [#1205](https://github.com/go-swagger/go-swagger/issues/1205).
+
+### Generate all models necessary for specified operation
+
+_Use-case_: I'm specifying specific operations and I'd like to restrict the models to those needed for those operations. Is there a way to do that?
+
+**Answer:** when using the generate server command, a repeatable --operation=xxx is available to restrict the scope of operations.
+
+ > NOTE: this option is not available for `generate model`.
+
+Originally from issue [#1427](https://github.com/go-swagger/go-swagger/issues/1427).
+
+### Generated code changes the order of properties in struct
+
+_Use-case_: the generated struct has attributes ordered differently than the original specification
+
+Example:
+
+```yaml
+Product:
+    type: "object"
+    properties:
+      product_id:
+        type: "string"
+      name:
+        type: "string"
+```
+Generated by "swagger generate server":
+```go
+type Product struct {
+	Name string `json:"name,omitempty"`
+	ProductID string `json:"product_id,omitempty"`
+}
+```
+I want product_id be the first property of Product struct.
+Is there any way to keep the order of properties?
+
+**Answer:** try x-order: n extension
+
+Originally from issue [#1759](https://github.com/go-swagger/go-swagger/issues/1759).
+
+### Fail to use swagger generate model -name
+
+_Use-case_: I met a problem when I tried to rename the filename of the auto-generated model.
+
+Example:
+
+1. `swagger generate model -m ./models/vo  --name Person`
+`unknown models: Person`
+2. `swagger generate model -m ./models/vo  -name Person`
+`unknown models: ame`
+3. `swagger generate model -m ./models/vo  -name= Person`
+`unknown models: ame=`
+
+```json
+{
+  "swagger": "2.0",
+   "info": {
+        "version": "1.0.0",
+        "title": "Simple API",
+        "description": "A simple API to learn how to write OpenAPI Specification"
+    },
+   "schemes": [
+        "http"
+    ],
+  "paths": {
+      "/persons":{
+	      "get":{
+		      "summary":"获取一些目标person",
+			  "description": "Returns a list containing all persons.",
+			  "responses": {
+                    "200": {
+                        "description": "A list of Person",
+                        "schema": {
+                            "type": "array",
+                            "items": {
+                                "properties": {
+                                    "firstName": {
+                                        "type": "string"
+                                    },
+                                    "lastName": {
+                                        "type": "string"
+                                    },
+                                    "username": {
+                                        "type": "string"
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+		  }
+	}
+  }
+}
+```json
+
+**Answer:** you need to make it available with that name in the definitions section then it will know
+
+Originally from issue [#1517](https://github.com/go-swagger/go-swagger/issues/1517).
+
 -------------
 
-Back to [all contributions](README.md#all-contributed-questions)
+Back to [all contributions](README.md#all-contributed-questions)
diff --git a/docs/faq/faq_server.md b/docs/faq/faq_server.md
@@ -107,7 +107,7 @@ Can i pass it somehow via context or any other way to do that?
 >Lookup would be faster in that way because each operation has a unique id according to swagger specification.
 >The problem comes when I want to check against that ACL of mine...
 
-**Suggestions**: 
+**Suggestions**:
 This is possible in 2 ways.
 - first way is by using an authenticator,
 - the second way is making a middleware (not global)
@@ -167,7 +167,7 @@ that was a little confusing looking through the other examples and not seeing an
 
 _Similar use-case_: dependency injection
 
-Wouldn't it be better to have all the handlers automatically be part of a default struct that simply has a Context member variable or empty interface? 
+Wouldn't it be better to have all the handlers automatically be part of a default struct that simply has a Context member variable or empty interface?
 
 >That would save everyone a lot of copy/paste when we need to inject some info.
 >I mean, a different context than the one available on params.HTTPRequest.Context(),
@@ -217,7 +217,7 @@ Also keep in mind that `go-openapi` and `go-swagger` constitute a _toolkit_
 and provide you the *tools* to adapt to your own use case.
 The `swagger` command line and standard templates only covers general purpose use-cases.
 
-If you think your use-case would benefit to many people, feel free to make the necessary changes for your case to work and submitting a PR. 
+If you think your use-case would benefit to many people, feel free to make the necessary changes for your case to work and submitting a PR.
 
 Example config file for generation:
 ```YAML
@@ -295,7 +295,105 @@ This should be sufficient. However:
 >I decided against this because it seemed to just add complexity for little benefit.
 >I can be persuaded to implement such a responder though, and should somebody send a PR like that I would not say no to it.
 
-Originally from issue Originally from issue [#305](https://github.com/go-swagger/go-swagger/issues/305).
+Originally from issue [#305](https://github.com/go-swagger/go-swagger/issues/305).
+
+### OAuth authentication does not redirect to the authorization server
+_Use-Case_: oauth2 accessCode flow does not redirect to the authorization server
+
+> In my understanding, if the accessCode flow is used for oauth2 securitydefinition, the generated server could redirect the authentication to the oauth2 server, e.g., https://accounts.google.com/o/oauth2/v2/auth. However, my generated code does not perform the redirection. Could anyone help on this? Thanks.
+
+Like in:
+```yaml
+---
+swagger: '2.0'
+info:
+  title: oauth2 debug
+  version: 0.3.0
+produces:
+- application/json
+schemes:
+  - http
+basePath: /api
+securityDefinitions:
+  OauthSecurity:
+    type: oauth2
+    flow: accessCode
+    authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth'
+    tokenUrl: 'hhttps://www.googleapis.com/oauth2/v4/token'
+    scopes:
+      admin: Admin scope
+      user: User scope
+security:
+  - OauthSecurity:
+    - user
+paths:
+  /customers:
+  ....
+```
+
+
+> The generated server does not redirect the browser to the google login page.
+
+**Answer**: Redirection flow is for UI. The spec has them so your UI can do the redirection.
+
+Swagger 2.0 only defines those properties as hints for a UI to work,
+this doesn't have to be server side. At the same time the redirection flow is not supported in an API
+but you can use an OAuth 2.0 middleware from any library to get you that functionality
+
+Originally from issue [#1217](https://github.com/go-swagger/go-swagger/issues/1217).
+
+### HTTPS TLS Cipher Suites not supported by AWS Elastic LoadBalancer
+
+_Use-case_: AWS Elastic LoadBalancer forwards https requests to instances, and their security policy is 'ELBSecurityPolicy-2016-08'.
+However, while running the server on https, the server keeps on logging
+
+`http: TLS handshake error from 192.168.X.X:XXXXX: tls: no cipher suite supported by both client and server.`
+
+If we remove the cipher suites on the generated code, it resolves the issue -
+
+```golang
+CipherSuites: []uint16{
+  tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
+  tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
+  tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
+  tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
+},
+```
+
+The ELB security policy 'ELBSecurityPolicy-2016-08' does include these cipher suites, however all requests sent by the ELB are rejected by the server.
+
+**Answer**: you can generate the server with a different compatibility mode for the older generation of ciphers
+
+```
+swagger generate server --compatibility-mode=intermediate
+```
+
+Originally from issue [#1383](https://github.com/go-swagger/go-swagger/issues/1383).
+
+### Which mime types are supported?
+
+_Use-Case_: I seem to be unable to find supported mime-types that the API's can consume and produce. Any references?
+
+**Answer**: see the current list of supported media MIMEs [here](https://github.com/go-swagger/go-swagger/blob/3099f611ada66d42974160ac4e0ec475d24b7041/generator/support.go#L279)
+You can add more through the consumer producer mechanism.
+
+Originally from issue [#1022](https://github.com/go-swagger/go-swagger/issues/1022).
+
+### Is it possible to return error to main function of server?
+
+_Use-Case_: Is it possible to return error to main function of server?
+
+> For example, my server saves some configs in file, and I want that if config file is missing,
+> then server must be stopped with some error code. It is possible to do it with panic(err),
+> but I think it is not good way. So can I return error main function of server ?
+
+**Answer**: you can make your own main function.
+
+There is an example here: https://github.com/go-openapi/kvstore/blob/master/cmd/kvstored/main.go
+
+There is a command line argument to avoid overwriting the main when generating: `--exclude-main`.
+
+Originally from issue [#1060](https://github.com/go-swagger/go-swagger/issues/1060).
 
 -------------