diff --git a/docs/en/API/Swagger-Integration.md b/docs/en/API/Swagger-Integration.md new file mode 100644 index 0000000000..48ce252940 --- /dev/null +++ b/docs/en/API/Swagger-Integration.md @@ -0,0 +1,140 @@ +# Swagger Integration + +[Swagger (OpenAPI)](https://swagger.io/) is a language-agnostic specification for describing REST APIs. It allows both computers and humans to understand the capabilities of a REST API without direct access to the source code. Its main goals are to: + +- Minimize the amount of work needed to connect decoupled services. +- Reduce the amount of time needed to accurately document a service. + +ABP Framework offers a prebuilt module for full Swagger integration with small configurations. + +## Installation + +> This package is already installed by default with the startup template. So, most of the time, you don't need to install it manually. + +If installation is needed, it is suggested to use the [ABP CLI](CLI.md) to install this package. + +### Using the ABP CLI + +Open a command line window in the folder of the `Web` or `HttpApi.Host` project (.csproj file) and type the following command: + +```bash +abp add-package Volo.Abp.Swashbuckle +``` + +### Manual Installation + +If you want to manually install; + +1. Add the [Volo.Abp.Swashbuckle](https://www.nuget.org/packages/Volo.Abp.Swashbuckle) NuGet package to your `Web` or `HttpApi.Host` project: + + `Install-Package Volo.Abp.Swashbuckle` + +2. Add the `AbpSwashbuckleModule` to the dependency list of your module: + + ```csharp + [DependsOn( + //...other dependencies + typeof(AbpSwashbuckleModule) // <-- Add module dependency like that + )] + public class YourModule : AbpModule + { + } + ``` + +## Configuration + +First, we need to use `AddAbpSwaggerGen` extension to configure Swagger in `ConfigureServices` method of our module. + +```csharp +public override void ConfigureServices(ServiceConfigurationContext context) +{ + var services = contex.Services; + + //... other configarations. + + services.AddAbpSwaggerGen( + options => + { + options.SwaggerDoc("v1", new OpenApiInfo { Title = "Test API", Version = "v1" }); + options.DocInclusionPredicate((docName, description) => true); + options.CustomSchemaIds(type => type.FullName); + } + ); +} +``` + +Then we can use Swagger UI by calling `UseAbpSwaggerUI` method in the `OnApplicationInitialization` method of our module. + +```csharp +public override void OnApplicationInitialization(ApplicationInitializationContext context) +{ + var app = context.GetApplicationBuilder(); + + //... other configarations. + + app.UseAbpSwaggerUI(options => + { + options.SwaggerEndpoint("/swagger/v1/swagger.json", "Test API"); + }); + + //... other configarations. +} +``` + +## Using Swagger with OAUTH + +For non MVC/Tiered applications, we need to configure Swagger with OAUTH to handle authorization. + +> ABP Framework uses IdentityServer by default. To get more information about IDS, check this [documentation](Modules/IdentityServer.md). + + + +To do that, we need to use `AddAbpSwaggerGenWithOAuth` extension to configure Swagger with OAuth issuer and scopes in `ConfigureServices` method of our module. + +```csharp +public override void ConfigureServices(ServiceConfigurationContext context) +{ + var services = contex.Services; + + //... other configarations. + + services.AddAbpSwaggerGenWithOAuth( + "https://localhost:44341", // authority issuer + new Dictionary // + { // scopes + {"Test", "Test API"} // + }, // + options => + { + options.SwaggerDoc("v1", new OpenApiInfo { Title = "Test API", Version = "v1" }); + options.DocInclusionPredicate((docName, description) => true); + options.CustomSchemaIds(type => type.FullName); + } + ); +} +``` + +Then we can use Swagger UI by calling `UseAbpSwaggerUI` method in the `OnApplicationInitialization` method of our module. + +> Do not forget to set `OAuthClientId` and `OAuthClientSecret`. + + +```csharp +public override void OnApplicationInitialization(ApplicationInitializationContext context) +{ + var app = context.GetApplicationBuilder(); + + //... other configarations. + + app.UseAbpSwaggerUI(options => + { + options.SwaggerEndpoint("/swagger/v1/swagger.json", "Test API"); + + var configuration = context.ServiceProvider.GetRequiredService(); + options.OAuthClientId("Test_Swagger"); // clientId + options.OAuthClientSecret("1q2w3e*"); // clientSecret + }); + + //... other configarations. +} +``` \ No newline at end of file diff --git a/docs/en/Swagger.md b/docs/en/Swagger.md deleted file mode 100644 index 1fda8a0cd7..0000000000 --- a/docs/en/Swagger.md +++ /dev/null @@ -1,3 +0,0 @@ -# Swagger UI Integration - -TODO \ No newline at end of file diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index 5a2b18d365..398da988e4 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -578,6 +578,10 @@ "path": "API/Application-Configuration.md" } ] + }, + { + "text": "Swagger Integration", + "path": "API/Swagger-Integration.md" } ] },