github.com/go-swagger/go-swagger@v0.31.0/docs/usage/markdown.md (about)

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