From 8f7914037951d3d1e501866c86a2701889f2ae21 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ahmet=20=C3=87otur?= Date: Thu, 29 Jul 2021 16:05:42 +0300 Subject: [PATCH 1/2] Update Swagger.md --- docs/en/Swagger.md | 141 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 139 insertions(+), 2 deletions(-) diff --git a/docs/en/Swagger.md b/docs/en/Swagger.md index 1fda8a0cd7..48ce252940 100644 --- a/docs/en/Swagger.md +++ b/docs/en/Swagger.md @@ -1,3 +1,140 @@ -# Swagger UI Integration +# Swagger Integration -TODO \ No newline at end of file +[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 From 327e3425977d5eba640253b826806c2feaa40d5d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ahmet=20=C3=87otur?= Date: Mon, 2 Aug 2021 00:16:44 +0300 Subject: [PATCH 2/2] Update docs navigation for swagger integration doc. --- docs/en/{Swagger.md => API/Swagger-Integration.md} | 0 docs/en/docs-nav.json | 4 ++++ 2 files changed, 4 insertions(+) rename docs/en/{Swagger.md => API/Swagger-Integration.md} (100%) diff --git a/docs/en/Swagger.md b/docs/en/API/Swagger-Integration.md similarity index 100% rename from docs/en/Swagger.md rename to docs/en/API/Swagger-Integration.md 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" } ] },