Swashbuckle - Add Model and Example values to Swagger UI from a Model from another project

Question

I am using Swagger to document my .NET C# API and when my models are on another project Swagger just crashes and doesn't load anything.

When I load the sample WebAPI Project from Visual Studio it uses the models that are on the same project and it works:

Visual Studio Sample Project Example Image

But when I use Models from other project it just crashes before loading anything.

I have an API project and a Business Project. My models are View Models stored(and shared among other projects, therfore needed there) on my Buisiness Project.

Is there any way I can indicate to Swagger where my model definitions are?

score 6 · Answer 1 · answered Jun 13 '18 at 13:01

I faced same issue with Swashbuckle 5.6.0 and managed to fixed as follows. Enable XML documentation file on model objects containing project by changing project properties as follows.

Then go to SwaggerConfig.cs file of the api project and add xml comments file of model object project as follows.

c.IncludeXmlComments(string.Format(@"{0}\bin\WebApplication1.XML", System.AppDomain.CurrentDomain.BaseDirectory));
// New code line                            
c.IncludeXmlComments(string.Format(@"{0}\bin\core.XML", System.AppDomain.CurrentDomain.BaseDirectory));

Now you will have xml comments for model properties on swagger doc.

score 2 · Accepted Answer · edited May 23 '17 at 10:29

I have recently handled a similar scenario when I worked on a web API project which was hosted on IIS. I was required to enable xml documentations for all view models and models from two different projects.

Below is a summary of the main steps of the work:

Enable XML documentation for related projects (refer to here)
For each project, build it first and then include the xml file in the project. Set the property of the file "Copy to Output Directory" to be "Copy is newer" to ensure it is copied to the bin folder of the server.
In the Swagger config, invoke IncludeXmlComments() to include the XML documentation files as suggested by Simon88.

The key point is to ensure all xml documentation files are copied to the bin folder of the host server and Swagger UI knows where they are :-).

By the way, there are few similar questions/answers for this kind of issue. One is here

Hope it helps.

score 2 · Answer 3 · answered May 05 '22 at 13:09

Step 1: Update reference project .csproj file and add DocumentationFile

    <PropertyGroup>
        <TargetFramework>net6.0</TargetFramework>
        <ImplicitUsings>enable</ImplicitUsings>
        <Nullable>enable</Nullable>
        <GenerateDocumentationFile>True</GenerateDocumentationFile>
        <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(MSBuildThisFileName).xml</DocumentationFile>
    </PropertyGroup>

This will cause the build of the project to output XML document along with the assembly of compiled project inside the bin folder.

API/Web project can access all reference assembly with a reflection by calling Assembly.GetReferencedAssemblies() method on the currently executing assembly.

Step 2: Update swagger configuration

builder.Services.AddSwaggerGen(options =>
{
    options.CustomSchemaIds(type => type.ToString());

    var currentAssembly = Assembly.GetExecutingAssembly();
    var xmlDocs = currentAssembly.GetReferencedAssemblies()
        .Union(new AssemblyName[] { currentAssembly.GetName() })
        .Select(a => Path.Combine(Path.GetDirectoryName(currentAssembly.Location), $"{a.Name}.xml"))
        .Where(f => File.Exists(f)).ToArray();

    Array.ForEach(xmlDocs, (d) =>
    {
        options.IncludeXmlComments(d);
    });

});

score 0 · Answer 4 · answered Aug 29 '16 at 01:04

I am actually looking to do the same thing!

In the Swagger config i tried this, where the functions point to my XML documentation files.

c.IncludeXmlComments(GetXmlCommentsPathForControllers());
c.IncludeXmlComments(GetXmlCommentsPathForModels());

It's working fine for the controllers but not much is happening when i document the models.

score 0 · Answer 5 · answered Oct 31 '17 at 14:49

Source
1. Models
2. Web App

If the source of Web application and Model are in different projects, you can always generate the metadata xml and copy them as part of the build into a common location inside the web application.

So in this case the edit the project properties of Models to output xml to "..\WebApp\bin"

For generating dynamic examples, i would recommend you go through this link.

Swashbuckle - Add Model and Example values to Swagger UI from a Model from another project

5 Answers5

Linked