{"record":{"id":"06cdfbbc3b3832ac","repo":"RicoSuter/NSwag","slug":"the-swaggeruiroute-cannot-contain-documentname-placeholder","errorCode":null,"errorMessage":"The SwaggerUiRoute cannot contain '{documentName}' placeholder when SwaggerRoute is missing the placeholder.","messagePattern":"The SwaggerUiRoute cannot contain '(.+?)' placeholder when SwaggerRoute is missing the placeholder\\.","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"src/NSwag.AspNetCore/Extensions/NSwagApplicationBuilderExtensions.cs","lineNumber":220,"sourceCode":"                        if (documents.Count() == 1)\n                        {\n                            register(\n                                settings.ActualSwaggerDocumentPath.Replace(\"{documentName}\", documents.First().DocumentName),\n                                settings.ActualSwaggerUiPath.Replace(\"{documentName}\", documents.First().DocumentName));\n                        }\n                        else\n                        {\n                            throw new NotSupportedException(\"This UI does not support multiple documents per UI: \" +\n                                \"Do not use '{documentName}' placeholder in DocumentPath or Path.\");\n                        }\n                    }\n                }\n            }\n            else\n            {\n                if (settings.ActualSwaggerUiPath.Contains(\"{documentName}\"))\n                {\n                    throw new ArgumentException(\"The SwaggerUiRoute cannot contain '{documentName}' placeholder when SwaggerRoute is missing the placeholder.\");\n                }\n\n                // Register single ui with one document\n                register(settings.ActualSwaggerDocumentPath, settings.ActualSwaggerUiPath);\n            }\n        }\n    }\n}\n","sourceCodeStart":202,"sourceCodeEnd":229,"githubUrl":"https://github.com/RicoSuter/NSwag/blob/63daf8fcc3a25151b62eb4b326a1e8ea048a0d41/src/NSwag.AspNetCore/Extensions/NSwagApplicationBuilderExtensions.cs#L202-L229","documentation":"When the Swagger UI route (Path) contains the '{documentName}' placeholder but the document route (DocumentPath/SwaggerRoute) does not, the middleware has no consistent way to expand the placeholder per document and throws ArgumentException during UseSwaggerUi/UseReDoc setup. The placeholder must appear in both routes or in neither.","triggerScenarios":"app.UseSwaggerUi(options => { options.Path = \"/swagger/{documentName}\"; options.DocumentPath = \"/swagger/doc.json\"; }) — Path has the placeholder, DocumentPath does not.","commonSituations":"Hand-editing one route to include '{documentName}' for multi-document setups but forgetting to update the other; mixing samples from single- and multi-document documentation.","solutions":["Add the '{documentName}' placeholder to DocumentPath as well, e.g. \"/swagger/{documentName}/swagger.json\".","Or remove the placeholder from Path so both routes are placeholder-free.","Ensure both routes consistently use or omit the placeholder before calling UseSwaggerUi/UseReDoc."],"exampleFix":"// before\napp.UseSwaggerUi(options =>\n{\n    options.Path = \"/swagger/{documentName}\";\n    options.DocumentPath = \"/swagger/doc.json\";\n});\n// after\napp.UseSwaggerUi(options =>\n{\n    options.Path = \"/swagger/{documentName}\";\n    options.DocumentPath = \"/swagger/{documentName}/swagger.json\";\n});","handlingStrategy":"validation","validationCode":"bool uiHas = options.Path?.Contains(\"{documentName}\") == true;\nbool docHas = options.DocumentPath?.Contains(\"{documentName}\") == true;\nif (uiHas != docHas) throw new ArgumentException(\"'{documentName}' must appear in both Path and DocumentPath, or in neither.\");","typeGuard":"bool IsConsistentPlaceholder(string path, string docPath) => path?.Contains(\"{documentName}\") == docPath?.Contains(\"{documentName}\");","tryCatchPattern":"try { app.UseSwaggerUi(configureUi); }\ncatch (ArgumentException ex) when (ex.Message.Contains(\"{documentName}\")) { logger.LogError(ex, \"Mismatched {documentName} placeholders in UI routes\"); throw; }","preventionTips":["Always configure Path and DocumentPath as a pair; template both or neither.","Centralize the route strings in constants so they cannot drift apart.","Add a startup integration test that runs the middleware configuration."],"tags":["aspnetcore","swagger-ui","route-configuration","nswag"],"backgroundTag":"conflicting-config-options","analyzedSha":"63daf8fcc3a25151b62eb4b326a1e8ea048a0d41","analyzedAt":"2026-09-14T11:38:15.205Z","contentChangedAt":"2026-09-14T11:38:15.205Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}