I am using Swashbuckle V4.0.0 with Asp.Net Core 2.2. I am using XML comments to document my Swagger. When I get the swagger via the HTTP endpoints it all works great. When I run dotnet swagger tofile I get the swagger but no XML comments included. Has anyone else had XML comments work via the CLI tool?
I have looked at the Swashbuckle CLI code and I am not sure how it calls my startup code when it create the builder. I have included my code for how I tell Swashbuckle which files to use. This code is in Startup.ConfigureServices. I have XML files in my main project and a couple of library projects so I wrote a function to go find them. This function returns valid files and works perfectly when requesting swagger from http. I am at loss for what I am doing wrong.
var xmlFiles = GetXmlFiles(apiName);
services.AddSwaggerGen(
options =>
{
// add a custom operation filter which sets default values
options.OperationFilter<SwaggerDefaultValues>();
// integrate xml comments
foreach (string s in xmlFiles)
{
options.IncludeXmlComments(s);
}
});
Related
b) After generating the .NET C# server stub, the documentation is not very verbose about how to use it:
You need to implement the logic yourself to handle whatever work the
API needs to do. Once the implementation is ready, you can deploy the
API locally or on your server. See the README.md file in the
downloaded archive to get started.
Is there any tutorial about how to use the code? I would like to use inheritance to avoid code changes of the generated code. But the documentation talks about just ignoring some generated files. The swagger support told me to just "migrate" the changes on every change. What is possible, but I hoped to be able to leave generated files untouched. Am I wrong here, is there no parctical need for this? I would like to use the server stub in a continuous integration environment.
One option you have is to customize the templates.
Clone the swagger-codegen repository.
Assuming you are using the latest stable v2 version of the code generation tool, then master branch is fine. Otherwise checkout the tag for the tool version you are using.
In Windows Explorer, open swagger-codegen\modules\swagger-codegen\src\main\resources\ and copy the aspnetcore directory. Paste that into your customer source code repository.
When next you run the codegen tool, provide the -t argument:
java -jar swagger-codegen-cli.jar generate
-i <your Open API spec URL/file>
-l aspnetcore
-o <outputdir>
-t <relative path to your>\aspnetcore
... other args as needed
Now you can modify those templates with custom code. For example, you could have an external library with a new base controller class that provides some generic business logic. Then you could modify the controller.mustache file to reference your base class. Just one of many examples. Add your custom templates to your source control for continuous integration.
Caveats: There is a controller.mustache file directly in aspnetcore and another in aspnetcore\2.1. In studying the source code, I see that the 2.1 folder is used for any version of ASP.NET Core other than 2.0. I'm new to this tool myself and have not fully figured out how to exploit it; the utility generates source code that will not build for me out of the box. It does not generate the security classes, but it does generate code that tries to use those security classes. Thus I'm having to comment out the security code in the templates.
I'm developing a REST Api using ASP.NET Core. I used to shared assembly info across my solution using a shared file containing common attributes such as AssemblyCompany, AssemblyCopyright, AssemblyTrademark and AssemblyVersion. In this way all of my projects in a solution would be compiled with the same Assembly info attributes.
In ASP.NET Core these attributes are now defined in the project.json file. Is there a way to share these attributes in a similar way?
In case others get by here and are looking for a solution that works with .Net Core > 2.1 and the new .csproj project files:
After some research I got it working using Directory.Build.props file in a parent directory. You can find the sample code and some more information in this repository.
With the exception of AssemblyVersion, the assembly attributes you mentioned can still be defined in a shared file. This file can be added to the project under "buildOptions".
Example:
{
"buildOptions": {
"compile": "../shared/AssemblyInfo.cs"
}
}
See https://learn.microsoft.com/en-us/dotnet/articles/core/tools/project-json#buildoptions for more details.
AssemblyVersion can't be shared because it is always generated from the "version" value in project.json. "version" defaults to 1.0.0 if not specified.
Other attributes, such as AssemblyCopyright, will not be generated if their corresponding field is left empty in project.json.
I have set up swagger for my webapi documentation. I am using Octopus to do the automatic deployment. Though i have specified the XmlDocument path as bin\test.xml in Project-< Properties -> build tab -> Output -> XML Documentation File, octopus deploy is not copying the test.xml inside bin directory on the test server.
I did the changes to the project release using the information from following link
swagger-ui returns 500 after deployment
Can anyone guide me what could be the problem please?
Thanks
Make sure that you include your xml file when crating nuget package
example from VSO package application step:
I am interested how can I create XML documentation file in VS2015 with ASP.NET MVC6 project? In older project types there was a checkbox called XML documentation file when you do right click on Properties -> Build.
You don't need to do anything special, it generates it by default and puts it inside the NuGet package for you.
Refer to here if you want to see where exactly this happens.
I have a MVC4 App created in VS 2010 with Umbraco 6 too and I've created a web deploy project which is used by my Team City CI server to deploy my website to a CI environment for testing.
On the CI server the first time I load the homepage (or any page) it loads perfectly fine. However the act of loading a page creates a App_Code folder on my CI server, and after that I get the message "The directory '/App_Code/' is not allowed because the application is precompiled". Removing the App_Code folder means that it once again works for one page load and the folder is created again.
Removing the PrecompiledApp.config file causes my site to not load with a YSOD stating "Object reference not set to an instance of an object." at the following point in the stack trace "Umbraco.Web.UmbracoModule.BeginRequest(HttpContextBase httpContext) +25"
To be clear, I don't have an App_Code folder in my project, and I don't want or need one. All I want is for it to stop creating one automatically upon page load! I've used Umbraco in VS and deployed in the same way many times before, just not with Umbraco 6 and in an MVC project.
Any ideas why App_Code is being automatically created and what I can do to stop it?
Many Thanks
Richard
I seem to use Umbraco in a similar way as you do, wrapping it as a MVC 4 project. Hence it becomes a "VS Web Application" instead of a "VS Web Site".
What is important to remember is that Umbraco originally wasn't made to be run as an application and a lot of the functionality in Umbraco is first and foremost directed to using App_Code.
The internal classes AssemblyExtensions, PluginManager, TypeHelper and the public class TypeFinder in Umbraco.Core have methods that are dependent on that the App_Code folder is there. Even if you don't need an App_Code in your solution Umbraco does, if you don't want to see it simply hide it from your solution. If you really don't want it remove all references to it in the source and create your own compilation of Umbraco.
== EDIT BELOW ==
After reading your comment and post again I created a small solution for your problem. The fact that Umbraco creates the App_Code is still because of the framework initialization that won't work without App_Code existing. But recompiling and creating an own dist of Umbraco will as OP points out create some extra maintenance when upgrading and so on.
It's not the ideal but most clean way to handle this matter to allow Umbraco to create the App_Code folder but also remove the same when the application have initialized. I'd use an IApplicationEventHandler. The sample code works on my box.
using Umbraco.Core;
using Umbraco.Core.IO;
namespace YourNamespace.EventHandlers
{
public class AppCodeEvents : IApplicationEventHandler
{
public void OnApplicationInitialized(UmbracoApplicationBase umbracoApplication, ApplicationContext applicationContext)
{ }
public void OnApplicationStarting(UmbracoApplicationBase umbracoApplication, ApplicationContext applicationContext)
{ }
public void OnApplicationStarted(UmbracoApplicationBase umbracoApplication, ApplicationContext applicationContext)
{
if (System.IO.Directory.Exists(IOHelper.MapPath(IOHelper.ResolveUrl("~/App_Code"))))
{
System.IO.Directory.Delete(IOHelper.MapPath(IOHelper.ResolveUrl("~/App_Code")));
}
}
}
}
If you are precompiling your site using a web deploy project, I assume you have all your references separated out from the project - which is a good thing. So, I think the simple answer here is don't precompile the site, just allow the web application to be built so that it pulls in the references and deploy the built project.
Personally, I find the best way to work with Umbraco v6 is via NuGet. Create an empty MVC4 project and use NuGet to add Umbraco v6. This will automatically sort out all the references for you. This is because those fantastic guys at Umbraco created two Nuget packages, one with the project files and the other with the core DLLs.
This means that when the site is built, the references are pulled in and updating the site is easy. It is just a matter of updating via NuGet.
This was happening me as well, turned out it was because a 'precompiledApp.config' file had somehow made its way onto the production server... not sure how that happened but once I deleted and recycled web app this stopped happening.