Cli tool --output path has to already exist and is counter-intuative

[Joren-Thijs]

Hello

I just had my first experience with the SwashBuckle CLI tool and ran into an issue. I copied the basic example for generating a swagger.json at build time.

<Target Name="SwaggerToFile" AfterTargets="AfterBuild">
    <Exec Command="swagger tofile &#45;-host http://example.com &#45;-output wwwroot/api-docs/v1/swagger.json &quot;$(TargetPath)&quot; v1" EnvironmentVariables="ASPNETCORE_ENVIRONMENT=Development" />
</Target>

It appears the --output argument directory we can specify has to already exist. This is very counter intuative for an optional argument of a cli tool that generates new content.

Error:

SwasbuckleCliRepro -> D:\repos\SwasbuckleCliRepro\bin\Debug\net6.0\SwasbuckleCliRepro.dll
  Unhandled exception. System.IO.DirectoryNotFoundException: Could not find a part of the path 'D:\repos\SwasbuckleCliRepro\wwwroot\api-docs\v1\swagger.json'.
     at Microsoft.Win32.SafeHandles.SafeFileHandle.CreateFile(String fullPath, FileMode mode, FileAccess access, FileShare share, FileOptions options)
     at Microsoft.Win32.SafeHandles.SafeFileHandle.Open(String fullPath, FileMode mode, FileAccess access, FileShare share, FileOptions options, Int64 preallocationSize)
     at System.IO.Strategies.OSFileStreamStrategy..ctor(String path, FileMode mode, FileAccess access, FileShare share, FileOptions options, Int64 preallocationSize)
     at System.IO.Strategies.FileStreamHelpers.ChooseStrategyCore(String path, FileMode mode, FileAccess access, FileShare share, FileOptions options, Int64 preallocationSize)
     at System.IO.Strategies.FileStreamHelpers.ChooseStrategy(FileStream fileStream, String path, FileMode mode, FileAccess access, FileShare share, Int32 bufferSize, FileOptions options, Int64 preallocationSize)
     at System.IO.StreamWriter.ValidateArgsAndOpenPath(String path, Boolean append, Encoding encoding, Int32 bufferSize)
     at System.IO.File.CreateText(String path)
     at Swashbuckle.AspNetCore.Cli.Program.<>c.<Main>b__0_4(IDictionary`2 namedArgs) in C:\projects\ahoy\src\Swashbuckle.AspNetCore.Cli\Program.cs:line 100
     at Swashbuckle.AspNetCore.Cli.CommandRunner.Run(IEnumerable`1 args) in C:\projects\ahoy\src\Swashbuckle.AspNetCore.Cli\CommandRunner.cs:line 68
D:\repos\SwasbuckleCliRepro\SwasbuckleCliRepro.csproj(14,5): error MSB3073: The command "swagger tofile --host http://example.com --output wwwroot/api-docs/v1/swagger.json "D:\repos\SwasbuckleCliRepro\bin\Debug\net6.0\SwasbuckleCliRepro.dll" v1" exited with code -532462766.
D:\repos\SwasbuckleCliRepro\SwasbuckleCliRepro.csproj(14,5): error MSB3073: The command "swagger tofile --host http://example.com --output wwwroot/api-docs/v1/swagger.json "D:\repos\SwasbuckleCliRepro\bin\Debug\net6.0\SwasbuckleCliRepro.dll" v1" exiBuild FAILED.

Request: Add a "Create directory if it does not exist" step to make cli tool more intuative and add ability to insert variables into output path, like the current ci environment, or the api version.

Would you accept a PR for this?

Minimal repro

[teauxfu]

I think this is a good suggestion, but I want to also say thanks for posting your example showing how to escape the first - as -. I was struggling to find a convenient way to comment out that line of my project file, as -- is invalid in an XML comment, and the CLI doesn't take single letter flag variants (eg. -o in lieu of --output). Cheers!

[GaTechThomas]

I just spent half an hour trying to sort out the CLI tool parameters. Here's the usage line:

Usage: dotnet swagger tofile [options] [startupassembly] [swaggerdoc]

In usage info, brackets usually indicate optional arguments. Minimally, when a required argument is not provided, the output should indicate at least the first required missing argument. Useful info in this Q&A:

https://stackoverflow.com/questions/9725675/is-there-a-standard-format-for-command-line-shell-help-text

Another pain is that the options item indicates the following:

--output: relative path where the Swagger will be output, defaults to stdout

I have found no way to make it work if --output is missing. Additionally the value is that of the path and file name.

Hopefully the following working example helps others:

dotnet swagger tofile --output .\MyWebAPI.dll v1

Where v1 is the name of the swagger document as seen in the setup via AddSwaggerGen.

[martincostello]

https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/2667#issuecomment-2053980759

[matt-lethargic]

Is there any movement on addressing this issue? It's totally unintuitive to supply an output path and then be told it doesn't exist :-(

[martincostello]

See the linked comment - a pull request would be welcome.