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

     1  # Generate markdown
     2  
     3  This is a command to generate a markdown document from a swagger spec.
     4  
     5  The generated doc is no substitute for advanced swagger documentation tools such as redoc:
     6  it provides a simple documentation for your API.
     7  
     8  The spec is canonicalized just like for code generation: the generated markdown represents
     9  operations and models just like your generated code sees them.
    10  
    11  The spec is flattened to be rendered as a self-contained document and all complex inlined models are
    12  defined as standalone models (documented as "inlined schemas").
    13  
    14  Known limitations:
    15  * validations are not rendered, for the sake of brevity
    16  
    17  ### Usage
    18  
    19  ```
    20  Usage:
    21    swagger [OPTIONS] generate markdown [markdown-OPTIONS]
    22  
    23  generate a markdown representation from the swagger spec
    24  
    25  Application Options:
    26    -q, --quiet                                                                     silence logs
    27        --log-output=LOG-FILE                                                       redirect logs to file
    28  
    29  Help Options:
    30    -h, --help                                                                      Show this help message
    31  
    32  [markdown command options]
    33            --output=                                                               the file to write the generated markdown. (default: markdown.md)
    34  
    35      Options common to all code generation commands:
    36        -f, --spec=                                                                 the spec file to use (default swagger.{json,yml,yaml})
    37        -t, --target=                                                               the base directory for generating the files (default: ./)
    38            --template=[stratoscale]                                                load contributed templates
    39        -T, --template-dir=                                                         alternative template override directory
    40        -C, --config-file=                                                          configuration file to use for overriding template options
    41        -r, --copyright-file=                                                       copyright file used to add copyright header
    42            --additional-initialism=                                                consecutive capitals that should be considered intialisms
    43            --allow-template-override                                               allows overriding protected templates
    44            --skip-validation                                                       skips validation of spec prior to generation
    45            --dump-data                                                             when present dumps the json for the template generator instead of generating
    46                                                                                    files
    47            --strict-responders                                                     Use strict type for the handler return value
    48            --with-expand                                                           expands all $ref's in spec prior to generation (shorthand to
    49                                                                                    --with-flatten=expand)
    50            --with-flatten=[minimal|full|expand|verbose|noverbose|remove-unused]    flattens all $ref's in spec prior to generation (default: minimal, verbose)
    51  
    52      Options for model generation:
    53        -m, --model-package=                                                        the package to save the models (default: models)
    54        -M, --model=                                                                specify a model to include in generation, repeat for multiple (defaults to
    55                                                                                    all)
    56            --existing-models=                                                      use pre-generated models e.g. github.com/foobar/model
    57            --strict-additional-properties                                          disallow extra properties when additionalProperties is set to false
    58            --keep-spec-order                                                       keep schema properties order identical to spec file
    59            --struct-tags=                                                          the struct tags to generate, repeat for multiple (defaults to json)
    60  
    61      Options for operation generation:
    62        -O, --operation=                                                            specify an operation to include, repeat for multiple (defaults to all)
    63            --tags=                                                                 the tags to include, if not specified defaults to all
    64        -a, --api-package=                                                          the package to save the operations (default: operations)
    65            --with-enum-ci                                                          allow case-insensitive enumerations
    66            --skip-tag-packages                                                     skips the generation of tag-based operation packages, resulting in a flat generation
    67  ```