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

     1  # Serve a documentation site
     2  
     3  The toolkit has a command to serve a spec json document and optionally a UI for a given spec. 
     4  It embeds redoc, so you can use that documentation site without an internet connection.
     5  Or it can load your local spec into the swagger docs viewer at http://petstore.swagger.io
     6  
     7  <!--more-->
     8  
     9  ### Usage 
    10  
    11  To serve a documentation site:
    12  
    13  ```
    14  Usage:
    15    swagger [OPTIONS] serve [serve-OPTIONS]
    16  
    17  serve a spec and swagger or redoc documentation ui
    18  
    19  Application Options:
    20    -q, --quiet                         silence logs
    21        --log-output=LOG-FILE           redirect logs to file
    22  
    23  Help Options:
    24    -h, --help                          Show this help message
    25  
    26  [serve command options]
    27            --base-path=                the base path to serve the spec and UI at
    28        -F, --flavor=[redoc|swagger]    the flavor of docs, can be swagger or redoc (default: redoc)
    29            --doc-url=                  override the url which takes a url query param to render the doc ui
    30            --no-open                   when present won't open the the browser to show the url
    31            --no-ui                     when present, only the swagger spec will be served
    32        -p, --port=                     the port to serve this site [$PORT]
    33            --host=                     the interface to serve this site, defaults to 0.0.0.0 [$HOST]
    34  ```
    35  
    36  This will start a server with cors enabled so that sites on other domains can load your specification document. 
    37  
    38  ### Flavors
    39  
    40  At this moment the UI can be served into 2 flavors.
    41  
    42  #### Redoc
    43  
    44  The swagger source code has a middleware for embedding Redoc.
    45  So for the redoc flavor we make use of that and use it with the spec you have on disk.
    46  
    47  #### Swagger UI
    48  
    49  For the swagger flavor we use the UI hosted at http://petstore.swagger.io.
    50  The server has CORS enabled and appends the url for the spec JSON to the petstore url as a query string. 
    51  
    52  #### Your own UI
    53  
    54  You can use your own UI by pointing it to the spec served by this command.
    55  When no ui is being served, the terminal will print the url to the spec document.
    56  You can also use the `--doc-url` to provide another url as base. 
    57  The url to your documentation site for example, which would need to recognize the query param url to load the swagger spec from, through the browser.
    58  
    59  ### More
    60  
    61  There are some more options for this command which you can view with:
    62  
    63  ```
    64  swagger serve --help
    65  ```