{"record":{"id":"90ec91d11d087d08","repo":"RicoSuter/NSwag","slug":"this-ui-does-not-support-multiple-documents-per-ui-do-not","errorCode":null,"errorMessage":"This UI does not support multiple documents per UI: Do not use '{documentName}' placeholder in DocumentPath or Path.","messagePattern":"This UI does not support multiple documents per UI: Do not use '(.+?)' placeholder in DocumentPath or Path\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"src/NSwag.AspNetCore/Extensions/NSwagApplicationBuilderExtensions.cs","lineNumber":210,"sourceCode":"                else\n                {\n                    // Register single ui with multiple documents\n                    if (registerMultiple(documents))\n                    {\n                        register(settings.ActualSwaggerDocumentPath, settings.ActualSwaggerUiPath);\n                    }\n                    else\n                    {\n                        // If multiple documents is not supported and only one document is registered\n                        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}","sourceCodeStart":192,"sourceCodeEnd":228,"githubUrl":"https://github.com/RicoSuter/NSwag/blob/63daf8fcc3a25151b62eb4b326a1e8ea048a0d41/src/NSwag.AspNetCore/Extensions/NSwagApplicationBuilderExtensions.cs#L192-L228","documentation":"NSwag's Swagger UI/ReDoc middleware supports serving exactly one document per UI middleware when the '{documentName}' placeholder is used in the UI or document path. If multiple documents are registered AND the placeholder is present in DocumentPath or Path, the middleware cannot expand it to a single value and throws NotSupportedException from UseSwaggerUiWithDocumentNamePlaceholderExpanding (called via UseSwaggerUi and UseReDoc).","triggerScenarios":"Calling app.UseSwaggerUi(options) with options.DocumentPath or options.Path containing '{documentName}' while more than one OpenAPI document is registered in DI (multiple AddOpenApiDocument/AddSwaggerDocument calls).","commonSituations":"Copy-pasting the multi-document sample from docs but using the placeholder-based paths intended for single-document setups; registering a second API document later without updating the UI configuration.","solutions":["Remove the '{documentName}' placeholder from DocumentPath/Path so a single UI serves the first (single) document.","If you truly have multiple documents, use the placeholder-free overload and register each UI explicitly, or use UseSwaggerUi with the documents parameter.","Reduce registrations to one AddOpenApiDocument/AddSwaggerDocument call if multiple documents were unintentional."],"exampleFix":"// before\napp.UseSwaggerUi(options =>\n{\n    options.DocumentPath = \"swagger/{documentName}/swagger.json\";\n    options.Path = \"/swagger\";\n});\n// after\napp.UseSwaggerUi(options =>\n{\n    options.DocumentPath = \"/swagger/v1/swagger.json\";\n    options.Path = \"/swagger\";\n});","handlingStrategy":"validation","validationCode":"// before UseSwaggerUi\nvar hasPlaceholder = options.DocumentPath?.Contains(\"{documentName}\") == true || options.Path?.Contains(\"{documentName}\") == true;\nif (hasPlaceholder && numberOfRegisteredDocuments > 1)\n    throw new InvalidOperationException(\"Placeholder paths require exactly one registered document.\");","typeGuard":"bool IsSingleDocumentSetup(IEnumerable<string> documentNames) => documentNames.Take(2).Count() <= 1;","tryCatchPattern":"try { app.UseSwaggerUi(o => { o.Path = \"/swagger\"; o.DocumentPath = \"/swagger/{documentName}/swagger.json\"; }); }\ncatch (NotSupportedException ex) { logger.LogError(ex, \"UI path config incompatible with registered documents\"); throw; }","preventionTips":["Use the '{documentName}' placeholder only in true multi-document setups with per-document UI middleware.","Keep DocumentPath and Path consistent (both with or both without the placeholder).","Add a startup smoke test hitting /swagger to catch middleware config errors at boot."],"tags":["aspnetcore","swagger-ui","configuration","nswag"],"backgroundTag":"unsupported-operation","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"}