Improving documentation for --settings-file cli tool parameter

[Ekkeir]

Per documentation file for --settings-file: .. Specifying this option will ignore all other settings.

This does not seem to be precisely correct as --output parameter is still taken into account and allows to specify a name for a generated output file. This is a welcome feature as output file name doesn't seem to be configurable via a `.refitter' file.

Maybe it would help to reflect the option in the documentation.

[christianhelle]

@Ekkeir thanks for taking the time to report this

I'll update the docs and improve on the descriptions there

[christianhelle]

@all-contributors please add @Ekkeir for doc

[allcontributors]

@christianhelle

I've put up a pull request to add @Ekkeir! 🎉

[christianhelle]

@Ekkeir I'm changing the description text for --settings-file to Path to .refitter settings file. Specifying this will ignore all other settings (except for --output). Does that make more sense?

The help text for the CLI tool will look like this:

USAGE:
    refitter [URL or input file] [OPTIONS]

EXAMPLES:
    refitter ./openapi.json
    refitter https://petstore3.swagger.io/api/v3/openapi.yaml
    refitter ./openapi.json --settings-file ./openapi.refitter
    refitter ./openapi.json --namespace "Your.Namespace.Of.Choice.GeneratedCode" --output ./GeneratedCode.cs
    refitter ./openapi.json --namespace "Your.Namespace.Of.Choice.GeneratedCode" --internal
    refitter ./openapi.json --output ./IGeneratedCode.cs --interface-only
    refitter ./openapi.json --use-api-response
    refitter ./openapi.json --cancellation-tokens
    refitter ./openapi.json --no-operation-headers
    refitter ./openapi.json --no-accept-headers
    refitter ./openapi.json --use-iso-date-format
    refitter ./openapi.json --additional-namespace "Your.Additional.Namespace" --additional-namespace "Your.Other.Additional.Namespace"
    refitter ./openapi.json --multiple-interfaces ByEndpoint
    refitter ./openapi.json --tag Pet --tag Store --tag User
    refitter ./openapi.json --match-path '^/pet/.*'

ARGUMENTS:
    [URL or input file]    URL or file path to OpenAPI Specification file

OPTIONS:
                                      DEFAULT                                                                                                                       
    -h, --help                                         Prints help information                                                                                      
    -s, --settings-file                                Path to .refitter settings file. Specifying this will ignore all other settings (except for --output)        
    -n, --namespace                   GeneratedCode    Default namespace to use for generated types                                                                 
    -o, --output                      Output.cs        Path to Output file                                                                                          
        --no-auto-generated-header                     Don't add <auto-generated> header to output file                                                             
        --no-accept-headers                            Don't add <Accept> header to output file                                                                     
        --interface-only                               Don't generate contract types                                                                                
        --use-api-response                             Return Task<IApiResponse<T>> instead of Task<T>                                                              
        --internal                                     Set the accessibility of the generated types to 'internal'                                                   
        --cancellation-tokens                          Use cancellation tokens                                                                                      
        --no-operation-headers                         Don't generate operation headers                                                                             
        --no-logging                                   Don't log errors or collect telemetry                                                                        
        --additional-namespace                         Add additional namespace to generated types                                                                  
        --use-iso-date-format                          Explicitly format date query string parameters in ISO 8601 standard date format using delimiters (2023-06-15)
        --multiple-interfaces                          Generate a Refit interface for each endpoint. May be one of ByEndpoint, ByTag                                
        --match-path                                   Only include Paths that match the provided regular expression. May be set multiple times                     
        --tag                                          Only include Endpoints that contain this tag. May be set multiple times and result in OR'ed evaluation       
        --skip-validation                              Skip validation of the OpenAPI specification                                                                 

[Ekkeir]

@christianhelle Looks great to me.

An example could optionally be added for this case. Something like this

EXAMPLES:
    ...
    refitter ./openapi.json --settings-file ./openapi.refitter  --output ./GeneratedCode.cs
    ...

Thank you for a quick response!

[christianhelle]

An example could optionally be added for this case. Something like this

EXAMPLES:
    ...
    refitter ./openapi.json --settings-file ./openapi.refitter  --output ./GeneratedCode.cs
    ...

@Ekkeir That's a good idea. I just implemented this change:

USAGE:
    refitter [URL or input file] [OPTIONS]

EXAMPLES:
    refitter ./openapi.json
    refitter https://petstore3.swagger.io/api/v3/openapi.yaml
    refitter ./openapi.json --settings-file ./openapi.refitter --output ./GeneratedCode.cs
    refitter ./openapi.json --namespace "Your.Namespace.Of.Choice.GeneratedCode" --output ./GeneratedCode.cs
    refitter ./openapi.json --namespace "Your.Namespace.Of.Choice.GeneratedCode" --internal
    refitter ./openapi.json --output ./IGeneratedCode.cs --interface-only
    refitter ./openapi.json --use-api-response
    refitter ./openapi.json --cancellation-tokens
    refitter ./openapi.json --no-operation-headers
    refitter ./openapi.json --no-accept-headers
    refitter ./openapi.json --use-iso-date-format
    refitter ./openapi.json --additional-namespace "Your.Additional.Namespace" --additional-namespace "Your.Other.Additional.Namespace"
    refitter ./openapi.json --multiple-interfaces ByEndpoint
    refitter ./openapi.json --tag Pet --tag Store --tag User
    refitter ./openapi.json --match-path '^/pet/.*'

ARGUMENTS:
    [URL or input file]    URL or file path to OpenAPI Specification file

OPTIONS:
                                      DEFAULT                                                                                                                       
    -h, --help                                         Prints help information                                                                                      
    -s, --settings-file                                Path to .refitter settings file. Specifying this will ignore all other settings (except for --output)        
    -n, --namespace                   GeneratedCode    Default namespace to use for generated types                                                                 
    -o, --output                      Output.cs        Path to Output file                                                                                          
        --no-auto-generated-header                     Don't add <auto-generated> header to output file                                                             
        --no-accept-headers                            Don't add <Accept> header to output file                                                                     
        --interface-only                               Don't generate contract types                                                                                
        --use-api-response                             Return Task<IApiResponse<T>> instead of Task<T>                                                              
        --internal                                     Set the accessibility of the generated types to 'internal'                                                   
        --cancellation-tokens                          Use cancellation tokens                                                                                      
        --no-operation-headers                         Don't generate operation headers                                                                             
        --no-logging                                   Don't log errors or collect telemetry                                                                        
        --additional-namespace                         Add additional namespace to generated types                                                                  
        --use-iso-date-format                          Explicitly format date query string parameters in ISO 8601 standard date format using delimiters (2023-06-15)
        --multiple-interfaces                          Generate a Refit interface for each endpoint. May be one of ByEndpoint, ByTag                                
        --match-path                                   Only include Paths that match the provided regular expression. May be set multiple times                     
        --tag                                          Only include Endpoints that contain this tag. May be set multiple times and result in OR'ed evaluation       
        --skip-validation                              Skip validation of the OpenAPI specification