I use NSwag in an ASP.Net WebAPI project to generate a swagger interface - which works great.
Say I have a method I want to add some explanations to - how can I do that?
By comment I mean something that when a user of the API is looking at the documentation will see.
I have googled, binged and ... ducked? - but was unable to find anything about it. Maybe I am using wrong terms.
To use annotation-based documentation with NSwag you must install the package NSwag.Annotations.
Then you can use annotations like that:
[SwaggerResponse(HttpStatusCode.OK, typeof(MyResponseType), Description = "Returns the object containing data ...")]
You can use Document comments to achieve your goal. For example
/// <summary>This method changes the point's location by
/// the given x- and y-offsets.
/// <example>For example:
/// <code>
/// Point p = new Point(3,5);
/// p.Translate(-1,3);
/// </code>
/// results in <c>p</c>'s having the value (2,8).
/// </example>
/// </summary>
public void Translate(int xor, int yor) {
X += xor;
Y += yor;
}
Translate is your API method and you've added proper documentation comments NSwag will pick those up and show them when you explore the API via the API explorer. If that doesn't work add the following in your .csproj
<PropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
Alternatively to the XML approach posted in another answer you can use the Swashbuckle.AspNetCore.Annotations package as well if you prefer an attribute-based approach.
Related
Assuming this example:
[HttpGet("action/cancel/{actionID}", Name = "cancel-action")]
async public Task<ActionResult> ActionCancel(string actionID) {
return await DoAllTheStuffWith(actionStopID);
How can I make NSwag emit a description string for actionID. I tried
/// <param name="actionID">the ID of the action</param>
without result. I've also been searching for an attribute to add the description, but I didn't find one.
Any help appreciated
Michael
Got it. NSwag ignores the xml documentation file, if it set to another than the default name. Reverting to the default name and keeping method parameter names and route parameter names in sync made it.
I'm looking over the documentation on doc comments in Dart, and came across the following:
/// Links can be:
///
/// * https://www.just-a-bare-url.com
/// * [with the URL inline](https://google.com)
/// * [or separated out][ref link]
///
/// [ref link]: https://google.com
///
But I've noticed a couple of things when I'm trying this in IntelliJ:
I can't get the link to show as a hyperlink (when pressing ctrl + q to open documentation) when part of a list item (by starting the line with any of these 1. * - +)
I can't get the 1st or 3rd forms of link expression to work, even outside of a list.
I'm trying to add a doc comment to a method that uses a dependency, and link to the dependency in the comment. Here's the comment that I have:
/// Doing dot product with a layer of neurons and multiple inputs
///
/// Associated YT NNFS tutorial: [Part-3](*youtube link here*)
///
/// This uses the [ml_linalg][1] dependency. You can also use the [linalg][2] dependency
///
/// [1]: https://pub.dev/packages/ml_linalg
///
/// [2]: https://pub.dev/packages/linalg
Here's a screenshot of how IntelliJ renders the documentation. The youtube link shows fine (using the second approach from the documentation) but clutters up the doc comment for the writers/editors of the docs. But as you can see, the third form doesn't work at all. The text in the square brackets isn't turned into a link and the text in second set of square brackets is just concatenated onto the text of the first.
If anyone knows how I can add links to my doc comments as part of a list, as well as put a marker to the link and have the full URL at the end of the doc comment as in the 3rd example given, that would be greatly appreciated. Thanks so much in advance
Does anyone know how? I'm trying to make a method that the intellisense shows another name instead of the name you ta the method. example:
The code looks like this:
Public Shared Sub Anything(ByVal blablabla....)
(...)
End Sub
And I want to auto-complete the VisualStudio menu be like:
Async
Alalala
Anymethod
Anything - Like these
Basic
On mouse hover:
instead of...
Public Shared Sub Namespace.Anything(ByVal blablablbal....)
This is the summary...
put it:
Anything <expression>
This is the summary...
-or-
Sub Anything
This is the summary...
Any ideas? thx...
I believe you're talking about XML Comments. Without comments:
With comments:
And Intellisense then also displays the parameter information as you get to each parameter:
Sooooo, I hope my answer isn't too vague. I'd love to help you igure it out either way.
Basically - you have to override the XML Documentation that Intellisense uses, in order to MAP a new MethodName to a Differently-Named method within your assembly.
Intellisense uses an XML Skeleton to define the different properties of what you see. That Skeleton typically looks something like this:
<CodeElement type="Function">
<Template>
<summary/>
<param/>
<returns/>
<remarks/>
</Template>
<CompletionList>
<exception cref=""/>
<include file="" path=""/>
<param name=""/>
<remarks/>
<returns/>
<summary/>
</CompletionList>
</CodeElement>
You can use this template to generate the Intellisense data you're looking for. In real-life application, this would look something like this:
''' <summary>
'''
''' </summary>
''' <param name="str"></praram>
''' <returns></returns>
''' <remarks></remarks>
Function Anything(ByVal str As String) As String
Try
...
Now, this template is Editable
The Visual Basic compiler generates an XML document for your assembly with all the XML comments defined in the code. The compiler will also resolve symbols used in cref, permission, and name attributes, as well as file references in include elements.
The generated file doesn't show your commented members hierarchically. Rather, it is a flat list. It includes a unique ID string for each definition that allows the comments to be mapped back to their definitions in code (see Code Snippet below).
In this case, the string is M:Namespace.Anything(System.String). M stands for method, Namespace specifies the path, System.String the parameter type.
THIS is where you would override the NAME of the Method that INTELLISENSE sees, without effecting the actual Method itself.
<?xml version="1.0" ?>
<doc>
<assembly>
<name>AnyLib</name>
</assembly>
<members>
...
<member name="M:Namespace.Anything(System.String)">
<summary>Does something</summary>
<param name="str">str to pass into method</param>
<returns>A string</returns>
</member>
...
</members>
</doc>
You can generate the XML documentation file using either the command-line compiler or through the Visual Studio interface. If you are compiling with the command-line compiler, use options /doc or /doc+. That will generate an XML file by the same name and in the same path as the assembly. To specify a different file name, use /doc:file.
If you are using the Visual Studio interface, there's a setting that controls whether the XML documentation file is generated. To set it, double-click My Project in Solution Explorer to open the Project Designer. Navigate to the Compile tab. Find "Generate XML documentation file" at the bottom of the window, and make sure it is checked. By default this setting is on. It generates an XML file using the same name and path as the assembly
In short - yes, it is possible, but very cumbersome and makes re-using your code very difficult. Check this link for a more detailed overview:
https://msdn.microsoft.com/en-us/magazine/dd722812.aspx
I've found that searches that contain 'of', 'and', 'the', etc. will not return results because Lucene has removed stop words. So if I search for a item that had a title of "Aftermath of the first world war" I will get zero results.
But if I strip 'of' and 'the', then I am searching for "aftermath first world war". I will get the expected document back.
Does the ContentSearch API remove stop words from queries? Is this something one can configure Lucene to remove? Or should I remove these stop words before building my query?
Thanks
Adam
You can configure Sitecore Standard Analyzer to accept your own custom set of Stopwords.
Create an text file with the stopwords (one stop word per line) and then Make the below config changes in the Sitecore.ContentSearch.Lucene.DefaultIndexConfiguration.config file
<param desc="defaultAnalyzer" type="Sitecore.ContentSearch.LuceneProvider.Analyzers.DefaultPerFieldAnalyzer, Sitecore.ContentSearch.LuceneProvider">
<param desc="defaultAnalyzer" type="Lucene.Net.Analysis.Standard.StandardAnalyzer, Lucene.Net">
<param hint="version">Lucene_30</param>
<param desc="stopWords" type="System.IO.FileInfo, mscorlib">
<param hint="fileName">[FULL_PATH_TO_SITECORE_ROOT_FOLDER]\Data\indexes\stopwords.txt</param>
</param>
</param>
</param>
Further Reading : I have written an blog post about this issue and might be of help http://blog.horizontalintegration.com/2014/03/19/sitecore-standard-analyzer-managing-you-own-stop-words-filter/
I think this is the same problem with problem from this blog.
Can you try to follow the steps from the blog post?
Other option can be to create a custom analyzer and to give to the constructor your stopWords list.
Something like:
public class CustomAnalyzer : Lucene.Net.Analysis.Standard.StandardAnalyzer
{
private static Hashtable stopWords = new Hashtable()
{
{"of", "of"},
{"stopword2", "stopword2"}
};
public CustomAnalyzer() : base(Lucene.Net.Util.Version.LUCENE_30, stopWords)
{
}
}
After you modify you need to change your config file. A nice blog post about Analyzer you can find here.
P.S.: I didn't try my code if is really working.
The msbuild contains output tag. It has avialable attributes: TaskParameter and PropertyName, ItemName.
How they can be used? What are they containing?
Please, can you help me to understand and give an example? For example you can use xmlpeek task with output tag inside.
(I read documentation on msdn but I still don't get it. :( )
The question has been answered, but I will follow up with an example.
In the MSBuild community task Time, an output parameter Month can be set to a property called
CurrentMonth as follows:
<Time>
<Output TaskParameter="Month" PropertyName="CurrentMonth" />
</Time>
In the MSBuild Community task time source code the property Month inside the Time class looks like this:
[Output]
public string Month
{
get { return month; }
}
All properties mapped with an [Output] attribute can be set as a task parameter and
assigned a MSBuild property name as specified above.
To read more about the Time task, a CHM file is available in the MSI file available at the following URL: http://msbuildtasks.tigris.org/
These are a way of passing values back from the task to the MSBuild script. It is basically a way of mapping a property in the compiled task code that has been decorated with the [Output] attribute back to a property in your MSBuild file. This page gives you more details about it: MSDN: Output Element (MSBuild). This article also has a good example of it in action: How to auto-increment assembly version using a custom MSBuild task