Using `.` in Swagger OperationIds makes swagger client generators fail

[Mike Sigsworth]

This isn't a bug with the code. This is more a report of an issue with the doc examples and sample code.

In your samples/docs you have Swagger annotations like this:

[SwaggerOperation(
    Summary = "Creates a new Author",
    Description = "Creates a new Author",
    OperationId = "Author.Create",
    Tags = new[] { "AuthorEndpoint" })
]

Notice the OperationId above uses a . as a separator. This actually causes trouble when generating API Clients from the resulting swagger.json. You wind up with generated code like this:

public async Task<CreateAuthorResult> Author.Create(CreateAuthorRequest body, CancellationToken cancellationToken) { }

This fails to compile because it thinks Author is a namespace. The solution is to simply use a character that would be valid in a C# or TypeScript identifier, with the obvious choice being an underscore, e.g. Author_Create.

So, like I said, not a problem with ApiEndpoints itself, but a small discovery we made while using the samples on a recent project and using NSwag to generate a client in another project.

Also, you might be thinking, Yeah? Well, you know, that's just like uh, your opinion, man.. But the Open API spec has this to say about the operationId :

Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.

Anyways, do what you want with this information :) And thank you for this awesome library!

[Steve Smith]

Seems worth fixing, thanks! Would be good if that API spec were more specific about "common programming naming conventions" since plenty of things in programming might be named "Foo.Bar" and be perfectly valid (domain names, full qualified classes, methods, etc.). But I understand it to mean single variable/construct names, so I'll just switch to PascalCase without . or - or any separators.

[Mike Sigsworth]

I was going to submit a PR with the required changes and found this NSwagSwaggerGeneratorSettingsExtensions.cs. Seems like someone had this same issue in the past but chose to fix it differently. I didn't find anywhere in the repo that's using it though.