Skip to content

Latest commit

 

History

History
78 lines (64 loc) · 3.52 KB

README.md

File metadata and controls

78 lines (64 loc) · 3.52 KB
Raw

Logo

Elect.Web.Swagger

Author Top Nguyen

Overview

Installation

  • Package Manager 
    PM> Install-Package Elect.Web.Swagger
  • .NET CLI 
    dotnet add package Elect.Web.Swagger

See more information in Nuget.

Usage

  • Enable generate XML for your project: Edit your .csproj add the code below, feel free to change

    <!-- {namespace} is your root system namespace, eg: Elect.Web -->

<PropertyGroup>
    <!-- Generate XML file -->
    <DocumentationFile>{namespace}.xml</DocumentationFile>
    <!-- Disable warning for Controller/Action/Method not have block comment -->
    <NoWarn>1701;1702;1705;1591</NoWarn>
</PropertyGroup>

<ItemGroup>
    <!-- Copy to Ouput -->
   <Content Include="{namespace}.xml">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </Content>
</ItemGroup>

  • Add Service

    services.AddElectSwagger();

  • Use Middleware

    app.UseElectSwagger();

  • Config Display in API Document

    • You need specific config for Controller/Action to show in API Document by ShowInApiDoc Attribute, if not set, not show in API Document by default.
    • Use Attribute ShowInApiDoc in Controller or Action to Enable Action show in API Document.
    • Use Attribute HideInApiDoc in Controller or Action to Override ShowInApiDoc attribute => make Action not show in API Document.
      • Note: Use specific for each Action about Http Method such as [HttpGet], [HttpPost], [HttpPut], [HttpDelete] and Specific about request path by [Route()] attribute too.

  • Title for API Document

    • In your API Action need add comment /// to display title for API in Document

  • Group Configuration

    • Group Name will use the Controller Name by default. If you want to change it, use ApiDocGroup to config the group name.
    • You can config multiple Group Name for Action. So the Action will appear in multiple groups.

  • Additional Parameters for API Document

    • You can add additional parameter by ApiParameter
    • Example:
      • Add Attribute [ApiParameter("avatar1", Description = "Avatar File", In = ParameterIn.FormData, Type = ParameterType.File, IsRequire = true)].
      • Then Get Data form Form var avatarFile1 = HttpContext.Request.Form.Files.GetFile("avatar1").
    • View more in swagger document.

  • Access API Document

    • By default, API Document URL is "/developers".
    • You can config access key to control access permission by the ElectSwaggerOptions.

  • Advance Configuration

    • If you want to add more config for SwaggerGenOptions after Elect.Web.Swagger config it. Just add your config in ExtendOptions Property of ElectSwaggerOptions.

View Sample

License

Elect.Web.Swagger is licensed under the MIT License.