github.com/jamescostian/go-swagger@v0.30.4-0.20221130163922-68364d6b567b/docs/generate/cli.md (about)

     1  # Generate a CLI (command line tool) from swagger spec
     2  This toolkit can generate a CLI to interact with your server
     3  
     4  ### Features of generated app
     5  * auto-completion for bash, zsh, fish and powershell.
     6  * use config file to specify common flags.
     7  * each param and each field in body has a cli flag. etc.
     8  
     9  ### CLI usage
    10  ```
    11  Usage:
    12    swagger [OPTIONS] generate cli [cli-OPTIONS]
    13  
    14  generate a command line client tool from the swagger spec
    15  
    16  Application Options:
    17    -q, --quiet                                                                     silence logs
    18        --log-output=LOG-FILE                                                       redirect logs to file
    19  
    20  Help Options:
    21    -h, --help                                                                      Show this help message
    22  
    23  [cli command options]
    24        -c, --client-package=                                                       the package to save the client specific code (default: client)
    25        -P, --principal=                                                            the model to use for the security principal
    26            --default-scheme=                                                       the default scheme for this API (default: http)
    27            --principal-is-interface                                                the security principal provided is an interface, not a struct
    28            --default-produces=                                                     the default mime type that API operations produce (default:
    29                                                                                    application/json)
    30            --default-consumes=                                                     the default mime type that API operations consume (default:
    31                                                                                    application/json)
    32            --skip-models                                                           no models will be generated when this flag is specified
    33            --skip-operations                                                       no operations will be generated when this flag is specified
    34        -A, --name=                                                                 the name of the application, defaults to a mangled value of info.title
    35            --cli-app-name=                                                         the app name for the cli executable. useful for go install. (default:
    36                                                                                    cli)
    37  
    38      Options common to all code generation commands:
    39        -f, --spec=                                                                 the spec file to use (default swagger.{json,yml,yaml})
    40        -t, --target=                                                               the base directory for generating the files (default: ./)
    41            --template=[stratoscale]                                                load contributed templates
    42        -T, --template-dir=                                                         alternative template override directory
    43        -C, --config-file=                                                          configuration file to use for overriding template options
    44        -r, --copyright-file=                                                       copyright file used to add copyright header
    45            --additional-initialism=                                                consecutive capitals that should be considered intialisms
    46            --allow-template-override                                               allows overriding protected templates
    47            --skip-validation                                                       skips validation of spec prior to generation
    48            --dump-data                                                             when present dumps the json for the template generator instead of
    49                                                                                    generating files
    50            --strict-responders                                                     Use strict type for the handler return value
    51            --with-expand                                                           expands all $ref's in spec prior to generation (shorthand to
    52                                                                                    --with-flatten=expand)
    53            --with-flatten=[minimal|full|expand|verbose|noverbose|remove-unused]    flattens all $ref's in spec prior to generation (default: minimal,
    54                                                                                    verbose)
    55  
    56      Options for model generation:
    57        -m, --model-package=                                                        the package to save the models (default: models)
    58        -M, --model=                                                                specify a model to include in generation, repeat for multiple
    59                                                                                    (defaults to all)
    60            --existing-models=                                                      use pre-generated models e.g. github.com/foobar/model
    61            --strict-additional-properties                                          disallow extra properties when additionalProperties is set to false
    62            --keep-spec-order                                                       keep schema properties order identical to spec file
    63            --struct-tags=                                                          the struct tags to generate, repeat for multiple (defaults to json)
    64  
    65      Options for operation generation:
    66        -O, --operation=                                                            specify an operation to include, repeat for multiple (defaults to all)
    67            --tags=                                                                 the tags to include, if not specified defaults to all
    68        -a, --api-package=                                                          the package to save the operations (default: operations)
    69            --with-enum-ci                                                          allow case-insensitive enumerations
    70            --skip-tag-packages                                                     skips the generation of tag-based operation packages, resulting in a
    71                                                                                    flat generation
    72  ```
    73  
    74  ### Build a CLI
    75  There is an example cli and tutorial provided at: https://github.com/go-swagger/go-swagger/tree/master/examples/cli
    76  
    77  To generate a CLI:
    78  ```
    79  swagger generate cli -f [http-url|filepath] --cli-app-name [app-name]
    80  ```
    81  Cli is a wrapper of generated client code (see [client](./client.md) for details), so all client generation options are honored.
    82  
    83  To build the generated CLI code:
    84  ```
    85  go build cmd/<app-name>/main.go 
    86  ```
    87  Or install in your go/bin
    88  ```
    89  go install cmd/<app-name>/main.go
    90  ```
    91  
    92  See details of the generated app help message for usage
    93  ```
    94  <app name> help
    95  ```
    96  
    97  A more detailed/complicated example is generated CLI for docker engine: https://github.com/go-swagger/dockerctl