I have swagger configured in my solution and it is showing up the API documentation properly. Now recently I have developed some new APIs in the same solution and these are also showing up in API documentation and these projects also follow the same naming conventions.
Now my requirement is I want to segregate the new API documentation from the older ones so basically I want two JSON files generated one foe each, old API, AND new API.
My Swagger configuration looks like the following.
Config.EnableSwagger(#"api-docs/{apiVersion}",
c =>
{
c.SingleApiVersion("v1", "SAMPLE API");
c.UseFullTypeNameInSchemaIds();
c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
foreach (String x in Directory.GetFiles(Path.GetDirectoryName(Uri.UnescapeDataString(new UriBuilder(Assembly.GetExecutingAssembly().CodeBase).Path)), "*.dll")
.Where(f => Path.GetFileNameWithoutExtension(f).ToLower().Contains("sample") ****&& !Path.GetFileNameWithoutExtension(f).ToLower().Contains("sample.api"))****
.Select(f => String.Format(#"{0}\{1}.xml", Path.GetDirectoryName(f), Path.GetFileNameWithoutExtension(f)))
.Where(File.Exists))
{
c.IncludeXmlComments(x);
}
c.OperationFilter<AddRequiredHeaderParameter>();
});
My New API projects are named sample.api.test and old API projects are named sample.web.test.
I added the && part in the where clause to ignore picking my new files in the first JSON doc generation but of no luck. I am new to this and really don't know if it is possible to have two JSON depending on project names. Any help would be greatly appreciated.
I fixed this using IDocumentFilter as follows.
internal class SwaggerFilterOutControllers : IDocumentFilter
{
void IDocumentFilter.Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
{
var apiKeys = swaggerDoc.paths.Select(s => s.Key).ToList();
foreach (var apiKey in apiKeys)
{
if (swaggerDoc.info.title == "old API" && apiKey.StartsWith("/latapi"))
swaggerDoc.paths.Remove(apiKey);
else if (swaggerDoc.info.title == "New Public API" && !apiKey.StartsWith("/latapi"))
swaggerDoc.paths.Remove(apiKey);
}
}
}
and then in the enableswagger() method i called this filter as
c.DocumentFilter<SwaggerFilterOutControllers>();
Related
I am creating an Web Api using .Net Core 5. I want to implement error handling and return the response with the error. I found a article from Microsoft which suggested the following code. When I am implementing that code "HttpResponseException" is not found and I get a suggestion to install the nuget package for Microsoft.Aspnet.WebApi.Core. Once install it conflicting with the existing nuget package. I got this message "Microsoft.AspNet.WebApi.Core 5.2.8 was restored using .netFramework, Version=4.6.1..." As I said, I am trying to handling error as per best practices and my finding was to use Microsoft documentation in which it mentioned to use HttpResponseException (applicable scenario). If HttpResponseException is obsolete for .Net 5 what other option we have? Basically in the response when error occured, I want to send the customize ReasonPhrase.
public Product GetProduct(int id)
{
Product item = repository.Get(id);
if (item == null)
{
var resp = new HttpResponseMessage(HttpStatusCode.NotFound)
{
Content = new StringContent(string.Format("No product with ID = {0}", id)),
ReasonPhrase = "Product ID Not Found"
};
throw new HttpResponseException(resp);
}
return item;
}
After updating my .net core 2.1 project to .net-5 and swagger swashbuckle from 2 to 5.6.3 the swagger response examples are not getting displayed anymore. Is there a new best practice way on how to solve this problem?
On 2.1 i have added some definitions on top of my controller.
[SwaggerResponse(409, Type = typeof(IEnumerable<ErrorObjects>))]
[SwaggerResponseExample(409, typeof(MethodResponseErrors))]
And in addition to this i implemented the MethodResponseErrors like this:
public class MethodResponseErrors : IExamplesProvider<List<ErrorObjects>>
{
List<ErrorObjects> IExamplesProvider<List<ErrorObjects>>.GetExamples()
{
return new List<ErrorObjects>
{
new Error1(),
new Error2(),
new Error3()
};
}
}
After this my response examples got displayed.
I am having difficulty using a custom index.html and other assets with swashbuckle. Swashbuckle/Swagger do not seem to recognizing or using them at all. I do have app.UseDefaultFiles() and app.UseStaticFiles() set. I am trying to understand what I am doing incorrectly.
I have attempted to set up my configuration somewhat similar to what is defined on the Microsoft article without success. (https://learn.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?tabs=visual-studio)
I am presently using the files from the dist folder referenced in the article (https://github.com/swagger-api/swagger-ui/tree/2.x/dist) along with the custom css file provided.
My index.html file is located under /wwwroot/swagger/ui
The custom css file is located under /wwwroot/swagger/ui/css (as custom.css)
Here is my Startup.cs class.
public class Startup
{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}
public IConfiguration Configuration { get; }
// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc()
.AddJsonOptions(options =>
{
// Swagger - Format JSON
options.SerializerSettings.Formatting = Formatting.Indented;
});
// Register the Swagger generator, defining one or more Swagger documents
services.AddSwaggerGen(c =>
{
c.DescribeAllEnumsAsStrings();
c.DescribeStringEnumsInCamelCase();
// c.DescribeAllParametersInCamelCase();
c.SwaggerDoc("v1",
new Info
{
Title = "My Web API - v1",
Version = "v1",
Description = "New and improved version. A simple example ASP.NET Core Web API. "
}
);
c.SwaggerDoc("v2",
new Info
{
Title = "My Web API - v2",
Version = "v2",
Description = "New and improved version. A simple example ASP.NET Core Web API. "
}
);
// Set the comments path for the Swagger JSON and UI.
var basePath = AppContext.BaseDirectory;
var xmlPath = Path.Combine(basePath, "ApiTest.xml");
c.IncludeXmlComments(xmlPath);
});
}
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
string swaggerUIFilesPath = env.WebRootPath + "\\swagger\\ui";
if (!string.IsNullOrEmpty(swaggerUIFilesPath))
{
app.UseDefaultFiles();
app.UseStaticFiles(new StaticFileOptions
{
FileProvider = new PhysicalFileProvider(swaggerUIFilesPath),
RequestPath = new PathString("/api-docs"),
});
}
// Enable middleware to serve generated Swagger as a JSON endpoint.
app.UseSwagger(c =>
{
c.RouteTemplate = "api-docs/{documentName}/swagger.json";
});
// Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), specifying the Swagger JSON endpoint.
app.UseSwaggerUI(c =>
{
//c.ShowJsonEditor();
c.RoutePrefix = "api-docs";
c.SwaggerEndpoint("/api-docs/v1/swagger.json", "My Web API - V1 ");
c.SwaggerEndpoint("/api-docs/v2/swagger.json", "My Web API - V2 ");
c.DocumentTitle("My Web API");
});
app.UseMvc();
}
}
My ultimate objective is to be able to use something like the slate style theme available here (https://github.com/omnifone/slate-swagger-ui). For right now, I am just trying to get Swashbuckle/Swagger to use the customized files referenced in the Microsoft documentation before trying to make the other files work.
I really do NOT want to try and convert my assets to embedded resources--since there will many of them. I just want to reference a normal index.html file and be able to use all of its referenced files.
What am I doing wrong?
Relevant Software Versions
.Net Core Version: 2.0.3
Swashbuckle.AspNetCore: 1.2.0
Windows 10 Enterprise Build 1703
Visual Studio 2017 Enterprise 15.5.2
Here is the minimum action I found to be necessary to replace SwashBuckle's index.html in a .NET Core project:
Get a copy of the original index.html from here: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/master/src/Swashbuckle.AspNetCore.SwaggerUI/index.html
Place that copy in some sub-folder of your project.
The file may have a different name, I chose:
\Resources\Swagger_Custom_index.html
Right-click that file in Solution Explorer, select 'Properties', select 'Configuration Properties' in left pane. Under 'Advanced' in right pane find entry 'Build Action' and set it to 'Embedded resource'. Click Ok.
In Startup.cs add the following line to your app.UseSwaggerUI() call:
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
//...
app.UseSwaggerUI(c =>
{
c.IndexStream = () => GetType().GetTypeInfo().Assembly.GetManifestResourceStream("Your.Default.Namespace.Resources.Swagger_Custom_index.html");
});
//...
}
The identifier for the file resource in the above GetManifestResourceStream method is composed of:
your default namespace (i.e. 'Your.Default.Namespace')
the sub-path of your resource (i.e. 'Resources')
the filename of your resource (i.e. 'Swagger_Custom_index.html')
All three parts are concatenated using dots (NO slashes or backslashes here).
If you don't use a sub-path but have your resource in root, just omit part 2.
For people who separate ApplicationBuilder config methods on ASP.NET Core:
If the separated method/class is static, it is not possible to call GetType() because an object reference is required.
In that case, switch GetType() to MethodBase.GetCurrentMethod().DeclaringType
c.IndexStream = () => MethodBase.GetCurrentMethod().DeclaringType.Assembly.GetManifestResourceStream("xxx.index.html");
I am having my api documetation in swagger. I would like to provide my users with Client sdk dropdown with options of php and java. below is my code.
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
services.AddSingleton(provider => Configuration);
services.AddTransient<IRegistrationRepository, ServiceUtilities>();
services.AddTransient<IClientServiceConnector, ClientServiceValidation>();
services.AddTransient<IEmailSender, EmailSender>();
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Swashbuckle.AspNetCore.Swagger.Info
{
Title = "Onboarding API",
Version = "V1",
Description = "API to generate lead and return the url",
TermsOfService = "Please see terms and conditions",
Contact = new Swashbuckle.AspNetCore.Swagger.Contact {Name = "teggggrap",Email = "support#dd.com.au",Url= "https://www.dd.com.au/" }
});
var basePath = PlatformServices.Default.Application.ApplicationBasePath;
var xmlPath = Path.Combine(basePath, "gf.RegistrationApplication.xml");
c.IncludeXmlComments(xmlPath);
});
services.AddCors(options =>
{
options.AddPolicy("AllowAll", policy =>
{
policy.AllowAnyOrigin();
policy.AllowAnyHeader();
policy.AllowAnyMethod();
});
});
}
The consumers of your API can generate swagger-codegen to create clients for your API in their language of choice. You probably don't want to host this yourself, but you could give your users instructions to go to https://editor.swagger.io/ where they can upload your API spec and generate it from there.
I've generate my php and JS SDKs with Codegen. It's pretty easy to use and then you can push the folder to a public Github repo and from your Swagger UI, you can tell your consumers to visit and follow the Getting started section !
It generates README.md and docs for each model.
Here is my sdk
I am using Swagger Swashbuckle to generate documentation. There are some methods in my controller and some properties in my models that I don't want to document.
Is there any arrtibute or the property to leave or ignore specific methods from documentation?
For the method, you have couple of option:
Use Obsolete attribute. Then, you have to set the action - c.IgnoreObsoleteActions(); within the swagger configuration
Create a custom attribute and a swagger document filter. The document filter should iterate through each method and remove the method documentation if the method is having the custom attribute
For the properties, you can use JsonIgnoreAttribute
In addition to c.IgnoreObsoleteActions(), there is also c.IgnoreObsoleteProperties(), which hides the property from the documentation.
JsonIgnoreAttribute will stop the property deserializing when being received as part of a POST request body, which may not be what you want if you only wish to change the documentation and not the functionality.
In more recent version of Swashbuckle (Core2/3) XmlIgnore/JsonIgnore don't seem to work for properties.
Alternatively you can change the property access modifier to internal. This should prevent serialization and generated documentation.
I'm not sure about hiding whole controllers, you will probably need to add filters in your Swagger setup. I do have an example of hiding certain endpoints (for convenience I have prefixed routes for running locally):
public void ConfigureServices(IServiceCollection services)
{
...
services.AddSwaggerGen(config => {
config.SwaggerDoc("v1",
new OpenApiInfo {
Version = "v1",
Title = "Foo API",
Description = "Does foo things.",
Contact = new OpenApiContact {
Name = "nope",
Email = "mail#example.org",
},
});
// Include XML comments in Swagger docs
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
config.IncludeXmlComments(xmlPath);
// Filter out prefixed routes
config.DocInclusionPredicate(
(name, desc) => !desc.RelativePath.ToLower().StartsWith("MyDevPrefix"));
});
}
Just a note since I was also trying to figure out the JsonIgnore for properties not working...
The issue seems to be that newer versions of Swashbuckle for .Net Core do not support NewtonSoft out of the box.
Install from NuGet
Package Manager : Install-Package Swashbuckle.AspNetCore.Newtonsoft -Version 5.6.2
CLI : dotnet add package --version 5.6.2 Swashbuckle.AspNetCore.Newtonsoft
Add code to startup.cs
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});
services.AddSwaggerGenNewtonsoftSupport(); // explicit opt-in - needs to be placed after AddSwaggerGen()
This worked for me, hope this helps someone else.
Here's a bit newer answer:
As other's mentioned - to ignore properties (both docs and real response) use attribute: [JsonIgnore]
To hide controller/actions from docs (the controller/action still exists, it is just hidden from docs) use attribute: [ApiExplorerSettings(IgnoreApi = true)]