github.com/thetreep/go-swagger@v0.0.0-20240223100711-35af64f14f01/docs/faq/faq_documenting.md (about)

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