search

RicoSuter / NSwag

The Swagger/OpenAPI toolchain for .NET, ASP.NET Core and TypeScript.
http://NSwag.org
MIT License
6.7k stars 1.24k forks source link

NSwag.AspNetCore - <param> XML comments are not parsed #1337

Closed piaste closed 6 years ago

piaste commented 6 years ago

Minimal repro: https://github.com/piaste/nswagscratch

Given the following method:

        /// <summary> gets foo 
        /// <param name="id">not actually used</param>
        /// </summary>        
        [HttpGet("{id}")]
        public ActionResult<string> Get(int id)
        {
            return "value";
        }

which creates the following XML doc file:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>nswagscratch</name>
    </assembly>
    <members>
        <member name="M:nswagscratch.Controllers.ValuesController.Get(System.Int32)">
            <summary> gets foo 
            <param name="id">not actually used</param>
            </summary>        
        </member>
    </members>
</doc>

the XML comment for the id parameter shows up in IntelliSense, but the NSwag generator dumps it in the general endpoint description:

image

RicoSuter commented 6 years ago

Did you add the required packages?

https://github.com/RSuter/NJsonSchema/wiki/XML-Documentation#net-core

piaste commented 6 years ago

Yes, my original project had them both in the output, and I've confirmed they appear in the repro as well. No difference.

Full content of the `/publish/` folder for win-x64 (click to expand) api-ms-win-core-console-l1-1-0.dll
api-ms-win-core-datetime-l1-1-0.dll
api-ms-win-core-debug-l1-1-0.dll
api-ms-win-core-errorhandling-l1-1-0.dll
api-ms-win-core-file-l1-1-0.dll
api-ms-win-core-file-l1-2-0.dll
api-ms-win-core-file-l2-1-0.dll
api-ms-win-core-handle-l1-1-0.dll
api-ms-win-core-heap-l1-1-0.dll
api-ms-win-core-interlocked-l1-1-0.dll
api-ms-win-core-libraryloader-l1-1-0.dll
api-ms-win-core-localization-l1-2-0.dll
api-ms-win-core-memory-l1-1-0.dll
api-ms-win-core-namedpipe-l1-1-0.dll
api-ms-win-core-processenvironment-l1-1-0.dll
api-ms-win-core-processthreads-l1-1-0.dll
api-ms-win-core-processthreads-l1-1-1.dll
api-ms-win-core-profile-l1-1-0.dll
api-ms-win-core-rtlsupport-l1-1-0.dll
api-ms-win-core-string-l1-1-0.dll
api-ms-win-core-synch-l1-1-0.dll
api-ms-win-core-synch-l1-2-0.dll
api-ms-win-core-sysinfo-l1-1-0.dll
api-ms-win-core-timezone-l1-1-0.dll
api-ms-win-core-util-l1-1-0.dll
api-ms-win-crt-conio-l1-1-0.dll
api-ms-win-crt-convert-l1-1-0.dll
api-ms-win-crt-environment-l1-1-0.dll
api-ms-win-crt-filesystem-l1-1-0.dll
api-ms-win-crt-heap-l1-1-0.dll
api-ms-win-crt-locale-l1-1-0.dll
api-ms-win-crt-math-l1-1-0.dll
api-ms-win-crt-multibyte-l1-1-0.dll
api-ms-win-crt-private-l1-1-0.dll
api-ms-win-crt-process-l1-1-0.dll
api-ms-win-crt-runtime-l1-1-0.dll
api-ms-win-crt-stdio-l1-1-0.dll
api-ms-win-crt-string-l1-1-0.dll
api-ms-win-crt-time-l1-1-0.dll
api-ms-win-crt-utility-l1-1-0.dll
appsettings.Development.json
appsettings.json
clrcompression.dll
clretwrc.dll
clrjit.dll
coreclr.dll
dbgshim.dll
hostfxr.dll
hostpolicy.dll
Microsoft.AspNetCore.Antiforgery.dll
Microsoft.AspNetCore.Authentication.Abstractions.dll
Microsoft.AspNetCore.Authentication.Cookies.dll
Microsoft.AspNetCore.Authentication.Core.dll
Microsoft.AspNetCore.Authentication.dll
Microsoft.AspNetCore.Authentication.Facebook.dll
Microsoft.AspNetCore.Authentication.Google.dll
Microsoft.AspNetCore.Authentication.JwtBearer.dll
Microsoft.AspNetCore.Authentication.MicrosoftAccount.dll
Microsoft.AspNetCore.Authentication.OAuth.dll
Microsoft.AspNetCore.Authentication.OpenIdConnect.dll
Microsoft.AspNetCore.Authentication.Twitter.dll
Microsoft.AspNetCore.Authentication.WsFederation.dll
Microsoft.AspNetCore.Authorization.dll
Microsoft.AspNetCore.Authorization.Policy.dll
Microsoft.AspNetCore.Connections.Abstractions.dll
Microsoft.AspNetCore.CookiePolicy.dll
Microsoft.AspNetCore.Cors.dll
Microsoft.AspNetCore.Cryptography.Internal.dll
Microsoft.AspNetCore.Cryptography.KeyDerivation.dll
Microsoft.AspNetCore.DataProtection.Abstractions.dll
Microsoft.AspNetCore.DataProtection.dll
Microsoft.AspNetCore.DataProtection.Extensions.dll
Microsoft.AspNetCore.Diagnostics.Abstractions.dll
Microsoft.AspNetCore.Diagnostics.dll
Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore.dll
Microsoft.AspNetCore.dll
Microsoft.AspNetCore.HostFiltering.dll
Microsoft.AspNetCore.Hosting.Abstractions.dll
Microsoft.AspNetCore.Hosting.dll
Microsoft.AspNetCore.Hosting.Server.Abstractions.dll
Microsoft.AspNetCore.Html.Abstractions.dll
Microsoft.AspNetCore.Http.Abstractions.dll
Microsoft.AspNetCore.Http.Connections.Common.dll
Microsoft.AspNetCore.Http.Connections.dll
Microsoft.AspNetCore.Http.dll
Microsoft.AspNetCore.Http.Extensions.dll
Microsoft.AspNetCore.Http.Features.dll
Microsoft.AspNetCore.HttpOverrides.dll
Microsoft.AspNetCore.HttpsPolicy.dll
Microsoft.AspNetCore.Identity.dll
Microsoft.AspNetCore.Identity.EntityFrameworkCore.dll
Microsoft.AspNetCore.Identity.UI.dll
Microsoft.AspNetCore.Identity.UI.Views.dll
Microsoft.AspNetCore.JsonPatch.dll
Microsoft.AspNetCore.Localization.dll
Microsoft.AspNetCore.Localization.Routing.dll
Microsoft.AspNetCore.MiddlewareAnalysis.dll
Microsoft.AspNetCore.Mvc.Abstractions.dll
Microsoft.AspNetCore.Mvc.ApiExplorer.dll
Microsoft.AspNetCore.Mvc.Core.dll
Microsoft.AspNetCore.Mvc.Cors.dll
Microsoft.AspNetCore.Mvc.DataAnnotations.dll
Microsoft.AspNetCore.Mvc.dll
Microsoft.AspNetCore.Mvc.Formatters.Json.dll
Microsoft.AspNetCore.Mvc.Formatters.Xml.dll
Microsoft.AspNetCore.Mvc.Localization.dll
Microsoft.AspNetCore.Mvc.Razor.dll
Microsoft.AspNetCore.Mvc.Razor.Extensions.dll
Microsoft.AspNetCore.Mvc.RazorPages.dll
Microsoft.AspNetCore.Mvc.TagHelpers.dll
Microsoft.AspNetCore.Mvc.ViewFeatures.dll
Microsoft.AspNetCore.NodeServices.dll
Microsoft.AspNetCore.Owin.dll
Microsoft.AspNetCore.Razor.dll
Microsoft.AspNetCore.Razor.Language.dll
Microsoft.AspNetCore.Razor.Runtime.dll
Microsoft.AspNetCore.ResponseCaching.Abstractions.dll
Microsoft.AspNetCore.ResponseCaching.dll
Microsoft.AspNetCore.ResponseCompression.dll
Microsoft.AspNetCore.Rewrite.dll
Microsoft.AspNetCore.Routing.Abstractions.dll
Microsoft.AspNetCore.Routing.dll
Microsoft.AspNetCore.Server.HttpSys.dll
Microsoft.AspNetCore.Server.IISIntegration.dll
Microsoft.AspNetCore.Server.Kestrel.Core.dll
Microsoft.AspNetCore.Server.Kestrel.dll
Microsoft.AspNetCore.Server.Kestrel.Https.dll
Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions.dll
Microsoft.AspNetCore.Server.Kestrel.Transport.Sockets.dll
Microsoft.AspNetCore.Session.dll
Microsoft.AspNetCore.SignalR.Common.dll
Microsoft.AspNetCore.SignalR.Core.dll
Microsoft.AspNetCore.SignalR.dll
Microsoft.AspNetCore.SignalR.Protocols.Json.dll
Microsoft.AspNetCore.SpaServices.dll
Microsoft.AspNetCore.SpaServices.Extensions.dll
Microsoft.AspNetCore.StaticFiles.dll
Microsoft.AspNetCore.WebSockets.dll
Microsoft.AspNetCore.WebUtilities.dll
Microsoft.CodeAnalysis.CSharp.dll
Microsoft.CodeAnalysis.dll
Microsoft.CodeAnalysis.Razor.dll
Microsoft.CSharp.dll
Microsoft.DiaSymReader.Native.amd64.dll
Microsoft.DotNet.PlatformAbstractions.dll
Microsoft.EntityFrameworkCore.Abstractions.dll
Microsoft.EntityFrameworkCore.Design.dll
Microsoft.EntityFrameworkCore.dll
Microsoft.EntityFrameworkCore.InMemory.dll
Microsoft.EntityFrameworkCore.Relational.dll
Microsoft.EntityFrameworkCore.SqlServer.dll
Microsoft.Extensions.Caching.Abstractions.dll
Microsoft.Extensions.Caching.Memory.dll
Microsoft.Extensions.Caching.SqlServer.dll
Microsoft.Extensions.Configuration.Abstractions.dll
Microsoft.Extensions.Configuration.Binder.dll
Microsoft.Extensions.Configuration.CommandLine.dll
Microsoft.Extensions.Configuration.dll
Microsoft.Extensions.Configuration.EnvironmentVariables.dll
Microsoft.Extensions.Configuration.FileExtensions.dll
Microsoft.Extensions.Configuration.Ini.dll
Microsoft.Extensions.Configuration.Json.dll
Microsoft.Extensions.Configuration.KeyPerFile.dll
Microsoft.Extensions.Configuration.UserSecrets.dll
Microsoft.Extensions.Configuration.Xml.dll
Microsoft.Extensions.DependencyInjection.Abstractions.dll
Microsoft.Extensions.DependencyInjection.dll
Microsoft.Extensions.DependencyModel.dll
Microsoft.Extensions.DiagnosticAdapter.dll
Microsoft.Extensions.FileProviders.Abstractions.dll
Microsoft.Extensions.FileProviders.Composite.dll
Microsoft.Extensions.FileProviders.Embedded.dll
Microsoft.Extensions.FileProviders.Physical.dll
Microsoft.Extensions.FileSystemGlobbing.dll
Microsoft.Extensions.Hosting.Abstractions.dll
Microsoft.Extensions.Hosting.dll
Microsoft.Extensions.Http.dll
Microsoft.Extensions.Identity.Core.dll
Microsoft.Extensions.Identity.Stores.dll
Microsoft.Extensions.Localization.Abstractions.dll
Microsoft.Extensions.Localization.dll
Microsoft.Extensions.Logging.Abstractions.dll
Microsoft.Extensions.Logging.Configuration.dll
Microsoft.Extensions.Logging.Console.dll
Microsoft.Extensions.Logging.Debug.dll
Microsoft.Extensions.Logging.dll
Microsoft.Extensions.Logging.EventSource.dll
Microsoft.Extensions.Logging.TraceSource.dll
Microsoft.Extensions.ObjectPool.dll
Microsoft.Extensions.Options.ConfigurationExtensions.dll
Microsoft.Extensions.Options.dll
Microsoft.Extensions.Primitives.dll
Microsoft.Extensions.WebEncoders.dll
Microsoft.IdentityModel.Logging.dll
Microsoft.IdentityModel.Protocols.dll
Microsoft.IdentityModel.Protocols.OpenIdConnect.dll
Microsoft.IdentityModel.Protocols.WsFederation.dll
Microsoft.IdentityModel.Tokens.dll
Microsoft.IdentityModel.Tokens.Saml.dll
Microsoft.IdentityModel.Xml.dll
Microsoft.Net.Http.Headers.dll
Microsoft.VisualBasic.dll
Microsoft.Win32.Primitives.dll
Microsoft.Win32.Registry.dll
mscordaccore.dll
mscordaccore_amd64_amd64_4.6.26426.02.dll
mscordbi.dll
mscorlib.dll
mscorrc.debug.dll
mscorrc.dll
netstandard.dll
Newtonsoft.Json.Bson.dll
Newtonsoft.Json.dll
NJsonSchema.dll
NSwag.Annotations.dll
NSwag.AspNetCore.dll
NSwag.Core.dll
NSwag.SwaggerGeneration.AspNetCore.dll
NSwag.SwaggerGeneration.dll
NSwag.SwaggerGeneration.WebApi.dll
nswagscratch.deps.json
nswagscratch.dll
nswagscratch.exe
nswagscratch.pdb
nswagscratch.runtimeconfig.json
nswagscratch.xml
Remotion.Linq.dll
sni.dll
sos.dll
SOS.NETCore.dll
sos_amd64_amd64_4.6.26426.02.dll
System.AppContext.dll
System.Buffers.dll
System.Collections.Concurrent.dll
System.Collections.dll
System.Collections.Immutable.dll
System.Collections.NonGeneric.dll
System.Collections.Specialized.dll
System.ComponentModel.Annotations.dll
System.ComponentModel.DataAnnotations.dll
System.ComponentModel.dll
System.ComponentModel.EventBasedAsync.dll
System.ComponentModel.Primitives.dll
System.ComponentModel.TypeConverter.dll
System.Configuration.dll
System.Console.dll
System.Core.dll
System.Data.Common.dll
System.Data.dll
System.Data.SqlClient.dll
System.Diagnostics.Contracts.dll
System.Diagnostics.Debug.dll
System.Diagnostics.DiagnosticSource.dll
System.Diagnostics.FileVersionInfo.dll
System.Diagnostics.Process.dll
System.Diagnostics.StackTrace.dll
System.Diagnostics.TextWriterTraceListener.dll
System.Diagnostics.Tools.dll
System.Diagnostics.TraceSource.dll
System.Diagnostics.Tracing.dll
System.dll
System.Drawing.dll
System.Drawing.Primitives.dll
System.Dynamic.Runtime.dll
System.Globalization.Calendars.dll
System.Globalization.dll
System.Globalization.Extensions.dll
System.IdentityModel.Tokens.Jwt.dll
System.Interactive.Async.dll
System.IO.Compression.Brotli.dll
System.IO.Compression.dll
System.IO.Compression.FileSystem.dll
System.IO.Compression.ZipFile.dll
System.IO.dll
System.IO.FileSystem.AccessControl.dll
System.IO.FileSystem.dll
System.IO.FileSystem.DriveInfo.dll
System.IO.FileSystem.Primitives.dll
System.IO.FileSystem.Watcher.dll
System.IO.IsolatedStorage.dll
System.IO.MemoryMappedFiles.dll
System.IO.Pipelines.dll
System.IO.Pipes.AccessControl.dll
System.IO.Pipes.dll
System.IO.UnmanagedMemoryStream.dll
System.Linq.dll
System.Linq.Expressions.dll
System.Linq.Parallel.dll
System.Linq.Queryable.dll
System.Memory.dll
System.Net.dll
System.Net.Http.dll
System.Net.Http.Formatting.dll
System.Net.HttpListener.dll
System.Net.Mail.dll
System.Net.NameResolution.dll
System.Net.NetworkInformation.dll
System.Net.Ping.dll
System.Net.Primitives.dll
System.Net.Requests.dll
System.Net.Security.dll
System.Net.ServicePoint.dll
System.Net.Sockets.dll
System.Net.WebClient.dll
System.Net.WebHeaderCollection.dll
System.Net.WebProxy.dll
System.Net.WebSockets.Client.dll
System.Net.WebSockets.dll
System.Net.WebSockets.WebSocketProtocol.dll
System.Numerics.dll
System.Numerics.Vectors.dll
System.ObjectModel.dll
System.Private.CoreLib.dll
System.Private.DataContractSerialization.dll
System.Private.Uri.dll
System.Private.Xml.dll
System.Private.Xml.Linq.dll
System.Reflection.DispatchProxy.dll
System.Reflection.dll
System.Reflection.Emit.dll
System.Reflection.Emit.ILGeneration.dll
System.Reflection.Emit.Lightweight.dll
System.Reflection.Extensions.dll
System.Reflection.Metadata.dll
System.Reflection.Primitives.dll
System.Reflection.TypeExtensions.dll
System.Resources.Reader.dll
System.Resources.ResourceManager.dll
System.Resources.Writer.dll
System.Runtime.CompilerServices.Unsafe.dll
System.Runtime.CompilerServices.VisualC.dll
System.Runtime.dll
System.Runtime.Extensions.dll
System.Runtime.Handles.dll
System.Runtime.InteropServices.dll
System.Runtime.InteropServices.RuntimeInformation.dll
System.Runtime.InteropServices.WindowsRuntime.dll
System.Runtime.Loader.dll
System.Runtime.Numerics.dll
System.Runtime.Serialization.dll
System.Runtime.Serialization.Formatters.dll
System.Runtime.Serialization.Json.dll
System.Runtime.Serialization.Primitives.dll
System.Runtime.Serialization.Xml.dll
System.Security.AccessControl.dll
System.Security.Claims.dll
System.Security.Cryptography.Algorithms.dll
System.Security.Cryptography.Cng.dll
System.Security.Cryptography.Csp.dll
System.Security.Cryptography.Encoding.dll
System.Security.Cryptography.OpenSsl.dll
System.Security.Cryptography.Pkcs.dll
System.Security.Cryptography.Primitives.dll
System.Security.Cryptography.X509Certificates.dll
System.Security.Cryptography.Xml.dll
System.Security.dll
System.Security.Permissions.dll
System.Security.Principal.dll
System.Security.Principal.Windows.dll
System.Security.SecureString.dll
System.ServiceModel.Web.dll
System.ServiceProcess.dll
System.Text.Encoding.CodePages.dll
System.Text.Encoding.dll
System.Text.Encoding.Extensions.dll
System.Text.Encodings.Web.dll
System.Text.RegularExpressions.dll
System.Threading.Channels.dll
System.Threading.dll
System.Threading.Overlapped.dll
System.Threading.Tasks.Dataflow.dll
System.Threading.Tasks.dll
System.Threading.Tasks.Extensions.dll
System.Threading.Tasks.Parallel.dll
System.Threading.Thread.dll
System.Threading.ThreadPool.dll
System.Threading.Timer.dll
System.Transactions.dll
System.Transactions.Local.dll
System.ValueTuple.dll
System.Web.dll
System.Web.HttpUtility.dll
System.Windows.dll
System.Xml.dll
System.Xml.Linq.dll
System.Xml.ReaderWriter.dll
System.Xml.Serialization.dll
System.Xml.XDocument.dll
System.Xml.XmlDocument.dll
System.Xml.XmlSerializer.dll
System.Xml.XPath.dll
System.Xml.XPath.XDocument.dll
ucrtbase.dll
web.config
WindowsBase.dll
RicoSuter commented 6 years ago

Yes, but i cannot see the .xml doc files in this listing?

piaste commented 6 years ago

It's in there:

nswagscratch.xml

The content of that file is what I posted in the first post.

(Besides, if it couldn't find the file, NSwag wouldn't show any comment text.)

RicoSuter commented 6 years ago

ATM nswag searches for xml docs with the same name as the assembly but with .xml extension

RicoSuter commented 6 years ago

Just saw that your xml summary shows up in the screenshot!? Where’s the problem?

RicoSuter commented 6 years ago

Ah i see: The xml param tag must not be placed into the summary tag but i think below...