github.com/kaisawind/go-swagger@v0.19.0/docs/faq/faq_documenting.md (about)

     1  <!-- Questions about the serve UI use-case -->
     2  ### Serving swagger-ui with the API Server
     3  _Use-Case_: I was trying to serve swagger-ui from the generated API Server and
     4  I didn't find a straightforward enough way in the docs,
     5  so I've created my own swagger-ui middleware:
     6  
     7  ```golang
     8  func setupGlobalMiddleware(handler http.Handler) http.Handler {
     9      return uiMiddleware(handler)
    10  }
    11  
    12  func uiMiddleware(handler http.Handler) http.Handler {
    13      return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    14          // Shortcut helpers for swagger-ui
    15          if r.URL.Path == "/swagger-ui" || r.URL.Path == "/api/help" {
    16              http.Redirect(w, r, "/swagger-ui/", http.StatusFound)
    17              return
    18          }
    19          // Serving ./swagger-ui/
    20          if strings.Index(r.URL.Path, "/swagger-ui/") == 0 {
    21              http.StripPrefix("/swagger-ui/", http.FileServer(http.Dir("swagger-ui"))).ServeHTTP(w, r)
    22              return
    23          }
    24          handler.ServeHTTP(w, r)
    25      })
    26  }
    27  ```
    28  
    29  *Can this be achieved any easier?*
    30  
    31  **Answer**: I think that's the way to do it.
    32  
    33  At some point I included an embedded version of the swagger-ui in this toolkit but it became annoying to keep up to date
    34  and severely bloated the size of my binary.
    35  
    36  *What do you say if we add swagger-ui as git submodule, include this middleware in your binary and update the docs?*
    37  
    38  I'm reluctant to do so at this point in time because a git submodule break go-gettability.
    39  
    40  >I've had it included at one point but it's so much of a moving target that it would always be outdated.
    41  >On top of it it are a lot of javascript and html files and people haven't been over the moon when go-swagger gets
    42  >vendored and they see all of that.
    43  
    44  Originally from issue [#370](https://github.com/go-swagger/go-swagger/issues/370).
    45  
    46  See also: How to serve Swagger UI from a preexisting web app? [#1029](https://github.com/go-swagger/go-swagger/issues/1029).
    47  
    48  ### How to serve Swagger UI from a preexisting web app?
    49  _Use-Case_: Does go-swagger provide an `http.HandlerFunc` or other easy method for serving Swagger UI from a preexisting web app? 
    50  I want my web app to expose `/swagger-ui`, without using code generation, and without hosting a separate server.
    51  
    52  **Answer**: there are a few ways you can serve a UI.
    53  
    54  Use the middleware provided in the go-openapi/runtime package: https://github.com/go-openapi/runtime/blob/master/middleware/redoc.go
    55  
    56  Originally from issues [#1029](https://github.com/go-swagger/go-swagger/issues/1029) and [#976](https://github.com/go-swagger/go-swagger/issues/976)
    57  
    58  ### How to use swagger-ui cors?
    59  
    60  **Answer**: you can add a cors middleware.
    61  
    62  Like: https://github.com/rs/cors
    63  
    64  [Documentation on how to customize middleware](use/middleware.md)
    65  
    66  Working example (in `configure_name.go`):
    67  
    68  ```golang
    69  import "github.com/rs/cors"
    70  
    71  func setupGlobalMiddleware(handler http.Handler) http.Handler {
    72      handleCORS := cors.Default().Handler
    73      return handleCORS(handler)
    74  }
    75  ```
    76  
    77  Originally from issue [#481](https://github.com/go-swagger/go-swagger/issues/481).
    78  
    79  ### How to serve my UI files?
    80  _Use-Case_: I generated server code using go-swagger with my swagger.yaml file like below.
    81  ```bash
    82  $ swagger generate server --exclude-main -A myapp -t gen -f ./swagger.yaml
    83  ```
    84  And I want to add new handler to serve my own UI files. 
    85  In this case, is middleware only solution to serve UI files? Or can I add new handler to serve files without middleware?
    86  ```go
    87  // Handler example which I want to add to swagger server
    88  func pastaWorkspacePage(w http.ResponseWriter, r *http.Request) {
    89  	http.ServeFile(w, r, "./static/workspace.html")
    90  }
    91  ```
    92  
    93  I solved the problem using middleware.
    94  ```go
    95  func FileServerMiddleware(next http.Handler) http.Handler {
    96  	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    97  		if strings.HasPrefix(r.URL.Path, "/api") {
    98  			next.ServeHTTP(w, r)
    99  		} else {
   100  			http.FileServer(http.Dir("./static")).ServeHTTP(w, r)
   101  		}
   102  	})
   103  }
   104  ```
   105  But I'm not sure it is the best solution.
   106  
   107  **Hint:** more info on using middlewares is found here: https://goswagger.io/use/middleware.html
   108  That page also contains a link to a good explanation on how to create net/http middlewares.
   109  
   110  > An implementation example is provided by the go-swagger serve UI command. It constructs a server with a redoc middleware:
   111  > https://github.com/go-swagger/go-swagger/blob/f552963ac0dfdec0450f6749aeeeeb2d31cd5544/cmd/swagger/commands/serve.go#L35.
   112  
   113  Besides, every swagger generated server comes with the redoc UI baked in at `/{basepath}/docs`
   114  
   115  Originally from issue [#1375](https://github.com/go-swagger/go-swagger/issues/1375).
   116  
   117  -------------------
   118  
   119  Back to [all contributions](README.md#all-contributed-questions)