### Conventional Routing Example Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/README.md This snippet demonstrates conventional routing setup. Controllers using this method might not be discoverable by Swashbuckle. ```csharp app.UseMvc(routes => { // SwaggerGen won't find controllers that are routed via this technique. routes.MapRoute("default", "{controller=Home}/{action=Index}/{id?}"); }); ``` -------------------------------- ### Install Swashbuckle CLI as a Local Tool Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/docs/configure-and-customize-cli.md Creates a tool manifest and installs the CLI tool locally within the solution directory. ```terminal dotnet new tool-manifest ``` ```terminal dotnet tool install Swashbuckle.AspNetCore.Cli ``` -------------------------------- ### Install Swashbuckle CLI as a Global Tool Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/docs/configure-and-customize-cli.md Installs the CLI tool globally using the .NET SDK. ```terminal dotnet tool install -g Swashbuckle.AspNetCore.Cli ``` -------------------------------- ### Verify Swashbuckle CLI Installation Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/docs/configure-and-customize-cli.md Checks that the tool is installed and accessible by displaying help information. ```terminal swagger tofile --help ``` -------------------------------- ### GET /Products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/9_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=MultipleVersions.Startup_swaggerRequestUri=1.0.verified.txt Retrieves a list of products from the system. ```APIDOC ## GET /Products ### Description Retrieves a list of all available products. ### Method GET ### Endpoint /Products ### Parameters #### Query Parameters - **api-version** (string) - Required - The version of the API to use. ### Response #### Success Response (200) - **id** (integer) - The unique identifier of the product. - **description** (string) - The description of the product. #### Response Example [ { "id": 1, "description": "Sample Product" } ] ``` -------------------------------- ### GET /products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/9_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=OAuth2Integration.Startup_swaggerRequestUri=v1.verified.txt Retrieves a list of all products. ```APIDOC ## GET /products ### Description Retrieves a list of all products. ### Method GET ### Endpoint /products ### Response #### Success Response (200) - **Array of Products** (array) - A list of product objects. #### Response Example [ { "id": 1, "serialNo": "SN123", "status": 0 } ] ``` -------------------------------- ### GET /Products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/8_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=MultipleVersions.Startup_swaggerRequestUri=1.0.verified.txt Retrieves a list of products. ```APIDOC ## GET /Products ### Description Retrieves a list of products. ### Method GET ### Endpoint /Products ### Parameters #### Query Parameters - **api-version** (string) - Required - The version of the API to use. ### Response #### Success Response (200) - **id** (integer) - The unique identifier of the product. - **description** (string) - A description of the product. ``` -------------------------------- ### GET /products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/9_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=CustomUIIndex.Startup_swaggerRequestUri=v1.verified.txt Retrieves a list of all products. ```APIDOC ## GET /products ### Description Retrieves a list of all products. ### Method GET ### Endpoint /products ### Response #### Success Response (200) - **id** (integer) - - **description** (string) - #### Response Example { "example": "[\n {\n \"id\": 1,\n \"description\": \"Example product description\"\n }\n]" ``` -------------------------------- ### GET /products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/9_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=CliExample.Startup_swaggerRequestUri=v1.verified.txt Retrieves a list of all products. ```APIDOC ## GET /products ### Description Retrieves a list of all products. ### Method GET ### Endpoint /products ### Responses #### Success Response (200) - **id** (integer) - Unique identifier for the product. - **description** (string, nullable) - A description of the product. #### Response Example { "example": "[\n {\n \"id\": 1,\n \"description\": \"Example Product 1\"\n },\n {\n \"id\": 2,\n \"description\": \"Example Product 2\"\n }\n]" ``` -------------------------------- ### Get All Products API Definition Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/8_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=2.0.verified.txt Defines the GET /products/all endpoint for retrieving all products. Includes a sample JSON structure in its description. ```json { "Id":1, "Description":"", "Status": 0, "Status2": 1 } ``` -------------------------------- ### GET /products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/9_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=CustomUIConfig.Startup_swaggerRequestUri=v1.verified.txt Retrieves a list of all products. ```APIDOC ## GET /products ### Description Retrieves a list of all products. ### Method GET ### Endpoint /products ### Response #### Success Response (200) - **id** (integer) - Unique identifier for the product. - **description** (string) - Description of the product. #### Response Example { "example": "[{"id": 1, "description": "Example Product"}]" } ``` -------------------------------- ### GET /products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/8_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=OAuth2Integration.Startup_swaggerRequestUri=v1.verified.txt Retrieves a list of all products. ```APIDOC ## GET /products ### Description Retrieves a list of all products. ### Method GET ### Endpoint /products ### Response #### Success Response (200) - **Array of Product** (object) - A list of product objects. #### Response Example [ { "id": 1, "serialNo": "SN123", "status": 0 } ] ``` -------------------------------- ### GET /products/all Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/9_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=2.0.verified.txt Retrieves all products available in the system. ```APIDOC ## GET /products/all ### Description Get all products. ### Method GET ### Endpoint /products/all ### Response #### Success Response (200) - **Product** (array) - A list of all products. #### Response Example [ { "id": "123", "description": "Some product" } ] ``` -------------------------------- ### GET /products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/8_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=CliExample.Startup_swaggerRequestUri=v1.verified.txt Retrieves a list of all products. ```APIDOC ## GET /products ### Description Retrieves a list of all products. ### Method GET ### Endpoint /products ### Parameters ### Request Body ### Request Example ### Response #### Success Response (200) - **id** (integer) - - **description** (string) - #### Response Example { "id": 1, "description": "Example Product" } ``` -------------------------------- ### GET /products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=CustomUIConfig.Startup_swaggerRequestUri=v1.verified.txt Retrieves a list of all products. ```APIDOC ## GET /products ### Description Retrieves a list of all products. ### Method GET ### Endpoint /products ### Responses #### Success Response (200) - **id** (integer) - The unique identifier of the product. - **description** (string) - A description of the product. #### Response Example ```json [ { "id": 1, "description": "Example Product" } ] ``` ``` -------------------------------- ### GET /products/all Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/8_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=2.0.verified.txt Retrieves all products available in the system. ```APIDOC ## GET /products/all ### Description Get all products. ### Method GET ### Endpoint /products/all ### Response #### Success Response (200) - **Product** (array of Product) - #### Response Example ```json [ { "Id":1, "Description":"", "Status": 0, "Status2": 1 } ] ``` ``` -------------------------------- ### GET /products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/8_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=CustomUIIndex.Startup_swaggerRequestUri=v1.verified.txt Retrieves a list of all products. ```APIDOC ## GET /products ### Description Retrieves a list of all products. ### Method GET ### Endpoint /products ### Response #### Success Response (200) - **id** (integer) - The unique identifier of the product. - **description** (string) - A description of the product. #### Response Example { "example": "[{"id": 1, "description": "Example Product"}]" } ``` -------------------------------- ### GET /products/all Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=v1.verified.txt Retrieves all products available in the system. ```APIDOC ## GET /products/all ### Description Get all products. ### Method GET ### Endpoint /products/all ### Response #### Success Response (200) - **Products** (array) - A list of all products. ``` -------------------------------- ### GET /products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=CliExample.Startup_swaggerRequestUri=v1.verified.txt Retrieves a list of all products. ```APIDOC ## GET /products ### Description Retrieves a list of all products. ### Method GET ### Endpoint /products ### Responses #### Success Response (200) - **id** (integer) - Unique identifier for the product. - **description** (string) - A description of the product. #### Response Example ```json [ { "id": 1, "description": "Example Product" } ] ``` ``` -------------------------------- ### GET /promotions Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/9_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=3.1.verified.txt Retrieves a list of promotions. ```APIDOC ## GET /promotions ### Description Retrieves a list of promotions. ### Method GET ### Endpoint /promotions ### Response #### Success Response (200) - **OK** - Returns an array of Promotion objects. ``` -------------------------------- ### GET /products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/9_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_ForAutofaq.verified.txt Retrieves a list of all available products. ```APIDOC ## GET /products ### Description Retrieves a list of all products available in the system. ### Method GET ### Endpoint /products ### Response #### Success Response (200) - **array** (Product) - A list of product objects. #### Response Example [ { "id": 1, "description": "Sample Product" } ] ``` -------------------------------- ### GET /products/all Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=3.1.verified.txt Retrieves all products available in the system. ```APIDOC ## GET /products/all ### Description Get all products. ### Method GET ### Endpoint /products/all ### Response #### Success Response (200) - **Products** (array) - List of products #### Response Example [ { "Id": 1, "Description": "", "Status": 0, "Status2": 1 } ] ``` -------------------------------- ### GET /products/all Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/9_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=3.1.verified.txt Retrieves all products from the collection. ```APIDOC ## GET /products/all ### Description Get all products. ### Method GET ### Endpoint /products/all ### Response #### Success Response (200) - **Product[]** (array) - An array of all products. ``` -------------------------------- ### GET /products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/8_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=CustomUIConfig.Startup_swaggerRequestUri=v1.verified.txt Retrieves a list of all available products. ```APIDOC ## GET /products ### Description Retrieves a list of all products available in the system. ### Method GET ### Endpoint /products ### Response #### Success Response (200) - **id** (integer) - The unique identifier of the product. - **description** (string) - The description of the product. #### Response Example [ { "id": 1, "description": "Sample Product" } ] ``` -------------------------------- ### GET /products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_ForAutofaq.verified.txt Retrieves a list of all available products. ```APIDOC ## GET /products ### Description Retrieves a list of all products available in the system. ### Method GET ### Endpoint /products ### Response #### Success Response (200) - **Array of Products** (array) - A list of product objects. #### Response Example [ { "id": 1, "description": "Sample Product" } ] ``` -------------------------------- ### GET /promotions Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/8_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=3.1.verified.txt Retrieves a list of promotions. ```APIDOC ## GET /promotions ### Description Retrieves a list of promotions. ### Method GET ### Endpoint /promotions ### Response #### Success Response (200) - **schema** (array of Promotion) - An array of Promotion objects. ``` -------------------------------- ### GET /products/all Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/8_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=3.1.verified.txt Retrieves all products from the collection. ```APIDOC ## GET /products/all ### Description Get all products. ### Method GET ### Endpoint /products/all ### Response #### Success Response (200) - **products** (array[Product]) - A list of all products. #### Response Example ```json [ { "id": "123", "description": "Some product" } ] ``` ``` -------------------------------- ### GET /promotions Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=3.1.verified.txt Retrieves a list of promotions. ```APIDOC ## GET /promotions ### Description Retrieves a list of promotions. ### Method GET ### Endpoint /promotions ### Response #### Success Response (200) - **schema** - An array of items, each referring to#/components/schemas/Promotion ``` -------------------------------- ### GET /api/Products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/9_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=ConfigFromFile.Startup_swaggerRequestUri=v1.verified.txt Retrieves a list of products from the system. ```APIDOC ## GET /api/Products ### Description Retrieves a list of all available products. ### Method GET ### Endpoint /api/Products ### Response #### Success Response (200) - **items** (array) - A list of Product objects. #### Response Example [ { "foo": [[1, 2], [3, 4]] } ] ``` -------------------------------- ### GET /products/all Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=2.0.verified.txt Retrieves a list of all available products. ```APIDOC ## GET /products/all ### Description Get all products. ### Method GET ### Endpoint /products/all ### Response #### Success Response (200) - **array of Product** (array) - #### Response Example [ { "id": 1, "description": "", "status": 0, "status2": 1 } ] ``` -------------------------------- ### Get All Resources Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/9_0/VerifyTests.Swagger_IsValidJson_No_Startup_entryPointType=Authorization.Program_swaggerRequestUri=v1.verified.txt Retrieves a list of all available resources. ```APIDOC ## GET /resources ### Description Retrieves a list of all available resources. ### Method GET ### Endpoint /resources ### Response #### Success Response (200) - **items** (array of Resource) - A list of resources. #### Response Example { "example": [ { "id": 0, "name": "string" } ] } ``` -------------------------------- ### GET /api/Products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=ConfigFromFile.Startup_swaggerRequestUri=v1.verified.txt Retrieves a list of products from the system. ```APIDOC ## GET /api/Products ### Description Retrieves a list of all products. ### Method GET ### Endpoint /api/Products ### Response #### Success Response (200) - **items** (array) - A list of Product objects. #### Response Example [ { "foo": [[1, 2], [3, 4]] } ] ``` -------------------------------- ### Build the project Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/AGENTS.md Compiles the source code. ```bash dotnet build ``` -------------------------------- ### GET /products API Endpoint Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=v1.verified.txt This snippet defines the GET endpoint for searching products by keywords. It includes a query parameter 'kw' with a default value and an example. ```json { "tags": [ "CrudActions" ], "summary": "Searches the collection of products by description key words", "operationId": "SearchProducts", "parameters": [ { "name": "kw", "in": "query", "description": "A list of search terms", "schema": { "type": "string", "default": "foobar" }, "example": "hello" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } } } }, "x-purpose": "test" } ``` -------------------------------- ### Annotate Endpoints with XML Comments Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/docs/configure-and-customize-swaggergen.md Annotate your API endpoints with XML comments like , , , and to provide detailed descriptions in the OpenAPI documentation. This example shows how to document a GET request. ```cs /// /// Retrieves a specific product line by unique id /// /// Awesomeness! /// The product line id /// Product line retrieved /// Product line not found /// Oops! Can't lookup your product line right now [HttpGet("product/{id}")] [ProducesResponseType(typeof(ProductLine), 200)] [ProducesResponseType(404)] [ProducesResponseType(500)] public ProductLine GetProductBySystemId(int id) { // ... return new ProductLine(); } ``` -------------------------------- ### GET /todos Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.Swagger_IsValidJson_No_Startup_entryPointType=WebApi.Aot.Program_swaggerRequestUri=v1.verified.txt Retrieves a list of all Todo items. ```APIDOC ## GET /todos ### Description Retrieves a list of all Todo items. ### Method GET ### Endpoint /todos ### Response #### Success Response (200) - **items** (array) - A list of Todo objects. #### Response Example [ { "id": 1, "title": "Example Todo", "dueBy": "2023-12-31", "isComplete": false } ] ``` -------------------------------- ### GET /api/Products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/8_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=ConfigFromFile.Startup_swaggerRequestUri=v1.verified.txt Retrieves a list of all products available in the system. ```APIDOC ## GET /api/Products ### Description Retrieves a list of products. ### Method GET ### Endpoint /api/Products ### Response #### Success Response (200) - **body** (array) - A list of Product objects. #### Response Example [ { "foo": [[1, 2], [3, 4]] } ] ``` -------------------------------- ### POST /products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=3.1.verified.txt Creates a new product in the system. ```APIDOC ## POST /products ### Description Creates a product. ### Method POST ### Endpoint /products ### Request Body - **Product** (object) - Required - Represents a product ### Request Example { "id": "123", "description": "Some product" } ### Response #### Success Response (200) - **Product** (object) - Represents a product #### Response Example { "id": "123", "description": "Some product" } ``` -------------------------------- ### POST /products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=2.0.verified.txt Creates a new product in the system. ```APIDOC ## POST /products ### Description Creates a product. ### Method POST ### Endpoint /products ### Parameters #### Request Body - **body** (Product) - Required - ### Request Example { "id": "123", "description": "Some product" } ### Response #### Success Response (200) - **Product** (Product) - #### Response Example { "id": "123", "description": "Some product" } ``` -------------------------------- ### POST /products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=v1.verified.txt Creates a new product in the system. ```APIDOC ## POST /products ### Description Creates a product. ### Method POST ### Endpoint /products ### Request Body - **Product** (object) - Required - The product object to create. ### Response #### Success Response (200) - **Product** (object) - The created product. ``` -------------------------------- ### Get All Products Endpoint Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/8_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=v1.verified.txt Defines the GET /products/all endpoint for retrieving all products. It specifies the response content type and schema. ```json { "tags": [ "CrudActions" ], "summary": "Get all products", "description": "```\r\n{\r\n \"Id\":1,\r\n \"Description\":\"\",\r\n \"Status\": 0,\r\n \"Status2\": 1\r\n}\r\n \r\n```", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } } } }, "x-purpose": "test" } ``` -------------------------------- ### POST /products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/8_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=2.0.verified.txt Creates a new product in the system. ```APIDOC ## POST /products ### Description Creates a product. ### Method POST ### Endpoint /products ### Request Body - **body** (Product) - Required - ### Request Example ```json { "id": "123", "description": "Some product" } ``` ### Response #### Success Response (200) - **Product** (Product) - #### Response Example ```json { "id": "123", "description": "Some product" } ``` ``` -------------------------------- ### POST /products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/9_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=2.0.verified.txt Creates a new product in the system. ```APIDOC ## POST /products ### Description Creates a product. ### Method POST ### Endpoint /products ### Request Body - **body** (Product) - Required - Description of the product to be created. ### Request Example { "id": "123", "description": "Some product" } ### Response #### Success Response (200) - **Product** (Product) - Description of the created product. #### Response Example { "id": "123", "description": "Some product" } ``` -------------------------------- ### GET /annotations/AsParameters Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.Swagger_IsValidJson_No_Startup_entryPointType=WebApi.Program_swaggerRequestUri=v1.verified.txt This GET endpoint demonstrates various query parameters, including UUIDs, date-times, dates, times, DateTimeKind, and doubles, with some being required. ```APIDOC ## GET /annotations/AsParameters ### Description This endpoint showcases various query parameters including UUIDs, date-times, dates, times, DateTimeKind, and doubles. Some parameters are marked as required. ### Method GET ### Endpoint /annotations/AsParameters ### Parameters #### Query Parameters - **paramOne** (string) - Optional - Description (format: uuid) - **paramTwo** (string) - Required - Description (format: uuid) - **paramThree** (string) - Optional - Description (format: date-time) - **paramFour** (string) - Required - Description (format: date-time) - **paramFive** (string) - Optional - Description (format: date) - **paramSix** (string) - Required - Description (format: date) - **paramSeven** (string) - Optional - Description (format: time) - **paramEight** (string) - Required - Description (format: time) - **paramNine** (DateTimeKind) - Optional - Description - **paramTen** (DateTimeKind) - Required - Description - **paramEleven** (number) - Optional - Description (format: double) - **paramTwelve** (number) - Required - Description (format: double) ### Response #### Success Response (200) - **string** (string) - OK #### Response Example ```text OK ``` ``` -------------------------------- ### Create Product Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=GenericControllers.Startup_swaggerRequestUri=v1.verified.txt Creates a new product resource for a specific tenant. ```APIDOC ## POST /{tenantId}/products ### Description Creates a new product resource for a specific tenant. ### Method POST ### Endpoint `/{tenantId}/products` ### Parameters #### Path Parameters - **tenantId** (string) - Required - The ID of the tenant. #### Request Body - **(Product)** - Required - The product resource to create. ### Request Example ```json { "productId": "string", "name": "string", "description": "string" } ``` ### Response #### Success Response (201) - **(integer)** - The ID of the created product. #### Response Example ```json 123 ``` ``` -------------------------------- ### Get Product API Definition Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/8_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=2.0.verified.txt Defines the GET /products/{id} endpoint for retrieving a specific product by its ID. Specifies path parameter and response schema. ```json { "in": "path", "name": "id", "description": "The product id", "required": true, "type": "integer", "format": "int32" } ``` -------------------------------- ### GET /products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/9_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=3.1.verified.txt Searches the collection of products by description keywords. ```APIDOC ## GET /products ### Description Searches the collection of products by description key words. ### Method GET ### Endpoint /products ### Parameters #### Query Parameters - **kw** (string) - Optional - A list of search terms (default: foobar) ### Response #### Success Response (200) - **Product[]** (array) - An array of products matching the search criteria. ``` -------------------------------- ### GET /products/all API Endpoint Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=v1.verified.txt This snippet defines the GET endpoint for retrieving all products. It includes a description with a code block showing a sample JSON structure. ```json { "tags": [ "CrudActions" ], "summary": "Get all products", "description": "```\r\n{\r\n \"Id\":1,\r\n \"Description\":\"\",\r\n \"Status\": 0,\r\n \"Status2\": 1\r\n}\r\n \r\n```", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } } } }, "x-purpose": "test" } ``` -------------------------------- ### GET /products/{id} API Endpoint Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=v1.verified.txt This snippet defines the GET endpoint for retrieving a specific product by its ID. It includes a path parameter 'id' and specifies the response schema. ```json { "tags": [ "CrudActions" ], "summary": "Returns a specific product", "operationId": "GetProduct", "parameters": [ { "name": "id", "in": "path", "description": "The product id", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 111 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } } }, "x-purpose": "test" } ``` -------------------------------- ### POST /products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/9_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=OAuth2Integration.Startup_swaggerRequestUri=v1.verified.txt Creates a new product. ```APIDOC ## POST /products ### Description Creates a new product. ### Method POST ### Endpoint /products ### Request Body - **Product** (object) - The product object to create. ### Request Example { "id": 0, "serialNo": "string", "status": 0 } ``` -------------------------------- ### GET /products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/8_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=v1.verified.txt Searches the collection of products by description keywords. ```APIDOC ## GET /products ### Description Searches the collection of products by description key words. ### Method GET ### Endpoint /products ### Parameters #### Query Parameters - **kw** (string) - Optional - A list of search terms (default: "foobar"). ### Response #### Success Response (200) - **Products** (array) - A list of matching products. ``` -------------------------------- ### POST /products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/8_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=OAuth2Integration.Startup_swaggerRequestUri=v1.verified.txt Creates a new product. ```APIDOC ## POST /products ### Description Creates a new product. ### Method POST ### Endpoint /products ### Request Body - **Product** (object) - The product object to create. ### Request Example { "serialNo": "SN123", "status": 0 } ### Response #### Success Response (200) - **OK** (string) - Product created successfully. ``` -------------------------------- ### Get Specific Product Endpoint Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/8_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=v1.verified.txt Defines the GET /products/{id} endpoint for retrieving a specific product by its ID. It includes a path parameter for the product ID and specifies the response schema. ```json { "tags": [ "CrudActions" ], "summary": "Returns a specific product", "operationId": "GetProduct", "parameters": [ { "name": "id", "in": "path", "description": "The product id", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 111 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } } }, "x-purpose": "test" } ``` -------------------------------- ### GET /products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=v1.verified.txt Searches the collection of products by description keywords. ```APIDOC ## GET /products ### Description Searches the collection of products by description key words. ### Method GET ### Endpoint /products ### Parameters #### Query Parameters - **kw** (string) - Optional - A list of search terms (default: "foobar"). ### Response #### Success Response (200) - **Products** (array) - A list of products matching the search criteria. ``` -------------------------------- ### OperationId Example with Custom Naming Strategy Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/docs/configure-and-customize-swaggergen.md An example endpoint demonstrating how a custom naming strategy, like using the method name, would assign an `operationId`. The `operationId` must be unique. ```csharp // operationId = "GetProductById" [HttpGet("/product/{id}")] public IActionResult GetProductById(int id) { // ... return Ok(); } ``` -------------------------------- ### POST /resource Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.SwaggerGen.Test/snapshots/10_0/VerifyTests.ActionHasFileResult.verified.txt Creates a resource and returns a binary zip file. ```APIDOC ## POST /resource ### Description Creates a new resource and returns the result as a binary zip file. ### Method POST ### Endpoint /resource ### Response #### Success Response (200) - **body** (binary) - Returns a zip file (application/zip). ``` -------------------------------- ### GET /products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/8_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=3.1.verified.txt Searches the collection of products by description keywords. ```APIDOC ## GET /products ### Description Searches the collection of products by description key words. ### Method GET ### Endpoint /products ### Query Parameters - **kw** (string) - Optional - A list of search terms (default: foobar) ### Response #### Success Response (200) - **products** (array[Product]) - A list of products matching the search criteria. #### Response Example ```json [ { "id": "123", "description": "Some product" } ] ``` ``` -------------------------------- ### GET /products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=3.1.verified.txt Searches the collection of products by description keywords. ```APIDOC ## GET /products ### Description Searches the collection of products by description key words. ### Method GET ### Endpoint /products ### Parameters #### Query Parameters - **kw** (string) - Optional - A list of search terms (Default: "foobar") ### Response #### Success Response (200) - **Products** (array) - List of products #### Response Example [ { "id": "123", "description": "Some product" } ] ``` -------------------------------- ### Configure Swagger Middleware Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/wiki/Getting-started-with-Swashbuckle-on-ASP.NET-Core Enable the Swagger middleware and UI in the Configure method of Startup.cs. ```csharp app.UseSwagger(); app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); }); ``` -------------------------------- ### GET /todos Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/9_0/VerifyTests.Swagger_IsValidJson_No_Startup_entryPointType=WebApi.Aot.Program_swaggerRequestUri=v1.verified.txt Retrieves a list of all todos. ```APIDOC ## GET /todos ### Description Retrieves a list of all todos. ### Method GET ### Endpoint /todos ### Response #### Success Response (200) - **id** (integer) - Description of the id field - **title** (string) - Description of the title field - **dueBy** (string) - Description of the dueBy field - **isComplete** (boolean) - Description of the isComplete field #### Response Example { "example": "[\n {\n \"id\": 1,\n \"title\": \"Buy groceries\",\n \"dueBy\": \"2023-12-31\",\n \"isComplete\": false\n }\n]" } ``` -------------------------------- ### Build and test the project Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/AGENTS.md Executes the full build and test pipeline. ```powershell ./build.ps1 ``` -------------------------------- ### POST /{tenantId}/products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/9_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=GenericControllers.Startup_swaggerRequestUri=v1.verified.txt Creates a new product resource for the specified tenant. ```APIDOC ## POST /{tenantId}/products ### Description Creates a new product resource for the specified tenant. ### Method POST ### Endpoint /{tenantId}/products ### Parameters #### Path Parameters - **tenantId** (string) - Required - The unique identifier of the tenant. #### Request Body - **Product** (object) - Required - The product resource to create. ### Response #### Success Response (201) - **integer** (int32) - The ID of the created resource. ``` -------------------------------- ### GET /products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=CustomUIIndex.Startup_swaggerRequestUri=v1.verified.txt Retrieves a list of all products available in the system. ```APIDOC ## GET /products ### Description Retrieves a list of all products. ### Method GET ### Endpoint /products ### Response #### Success Response (200) - **id** (integer) - The unique identifier of the product. - **description** (string) - The description of the product. #### Response Example [ { "id": 1, "description": "Sample Product" } ] ``` -------------------------------- ### GET /unicorns Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/9_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=2.0.verified.txt Retrieves a list of unicorns. ```APIDOC ## GET /unicorns ### Description Retrieves a list of unicorns. ### Method GET ### Endpoint /unicorns ### Response #### Success Response (200) - **object** - OK ### Response Example { "example": { "key": "value" } } ``` -------------------------------- ### Example Schema Reference Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/docs/configure-and-customize-swaggergen.md Shows how complex types are referenced in the generated OpenAPI schema. ```yaml responses: { 200: { description: "OK", content: { "application/json": { schema: { $ref: "#/components/schemas/Product" } } } } } ``` -------------------------------- ### GET /unicorns Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/8_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=2.0.verified.txt Retrieves a list of unicorns. ```APIDOC ## GET /unicorns ### Description Retrieves a list of unicorns. ### Method GET ### Endpoint /unicorns ### Responses #### Success Response (200) - **description** (string) - OK - **schema** (object) - The response schema is an object with additional properties. ``` -------------------------------- ### Provide Custom ReDoc Index.html Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/docs/configure-and-customize-redoc.md To customize the ReDoc UI, provide your own index.html file as an embedded resource. Ensure the file is correctly referenced in the `IndexStream` option. ```csharp app.UseReDoc(options => { options.IndexStream = () => typeof(Program).Assembly .GetManifestResourceStream("CustomIndex.ReDoc.index.html"); // Requires file to be added as an embedded resource }); ``` ```xml ``` -------------------------------- ### Define POST /products request body Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=3.1.verified.txt Example of a POST request body structure for creating a product. ```text POST /products { "id": "123", "description": "Some product" } ``` -------------------------------- ### GET /resourceB Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.SwaggerGen.Test/snapshots/10_0/VerifyTests.GenerateSchema_PreservesIntermediateBaseProperties_WhenUsingOneOfPolymorphism.verified.txt Retrieves a resource of type DerivedClass. ```APIDOC ## GET /resourceB ### Description Retrieves a single resource of type DerivedClass. ### Method GET ### Endpoint /resourceB ### Response #### Success Response (200) - **BaseProperty** (string) - Inherited from BaseClass - **DerivedProperty** (string) - Property of DerivedClass #### Response Example { "BaseProperty": "string", "DerivedProperty": "string" } ``` -------------------------------- ### GET /WithOpenApi/weatherforecast Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/9_0/VerifyTests.TypesAreRenderedCorrectly.verified.txt Retrieves a list of weather forecasts. ```APIDOC ## GET /WithOpenApi/weatherforecast ### Description Retrieves a list of weather forecasts. ### Method GET ### Endpoint /WithOpenApi/weatherforecast ### Response #### Success Response (200) - **array** (items: WeatherForecast) - An array of WeatherForecast objects. #### Response Example [ { "date": "2023-10-27T10:00:00Z", "temperatureC": 25, "summary": "Hot" } ] ``` -------------------------------- ### GET /resource Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.SwaggerGen.Test/snapshots/10_0/VerifyTests.ActionsWithIllegalHeaderParameters_action=ActionWithContentTypeFromHeaderParameter.verified.txt Retrieves resource information from the server. ```APIDOC ## GET /resource ### Description Retrieves resource information. ### Method GET ### Endpoint /resource ### Parameters #### Header Parameters - **param** (string) - Optional - Custom header parameter ### Response #### Success Response (200) - **description** (string) - OK ``` -------------------------------- ### GET /files/{name} Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/9_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=2.0.verified.txt Retrieves a file by its name. ```APIDOC ## GET /files/{name} ### Description Retrieves a file based on the provided name path parameter. ### Method GET ### Endpoint /files/{name} ### Parameters #### Path Parameters - **name** (string) - Required - The name of the file to retrieve ### Response #### Success Response (200) - **binary** - The file content ``` -------------------------------- ### Add Swashbuckle.AspNetCore.Annotations NuGet Package Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/docs/configure-and-customize-annotations.md Install the Swashbuckle.AspNetCore.Annotations NuGet package using the .NET CLI. ```bash dotnet add package Swashbuckle.AspNetCore.Annotations ``` -------------------------------- ### Install Swashbuckle.AspNetCore NuGet Package Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/README.md Use the dotnet CLI to add the Swashbuckle.AspNetCore package to your project. ```terminal dotnet add package Swashbuckle.AspNetCore ``` -------------------------------- ### GET /Issue3013/Get Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/8_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=3.1.verified.txt Retrieves data related to Issue3013. ```APIDOC ## GET /Issue3013/Get ### Description Retrieves data related to Issue3013. ### Method GET ### Endpoint /Issue3013/Get ### Response #### Success Response (200) - **schema** (TestResponse) - The response schema is defined as TestResponse. - Content types: text/plain, application/json, text/json ``` -------------------------------- ### GET /weatherforecast Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/8_0/VerifyTests.Swagger_IsValidJson_No_Startup_entryPointType=WebApi.Map.Program_swaggerRequestUri=v1.verified.txt Retrieves a list of weather forecasts. ```APIDOC ## GET /weatherforecast ### Description Retrieves a list of weather forecasts. ### Method GET ### Endpoint /weatherforecast ### Responses #### Success Response (200) - **date** (string) - The date of the forecast. - **temperatureC** (integer) - The temperature in Celsius. - **summary** (string) - A summary of the weather conditions. #### Response Example ```json [ { "date": "2023-10-27T10:00:00Z", "temperatureC": 25, "summary": "Sunny" } ] ``` ``` -------------------------------- ### Enable Annotations for Inheritance and Polymorphism Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/docs/configure-and-customize-annotations.md Call this method in Startup.cs to enable Swashbuckle's annotation support for inheritance and polymorphism. ```csharp services.AddSwaggerGen(options => { options.EnableAnnotations(enableAnnotationsForInheritance: true, enableAnnotationsForPolymorphism: true); }); ``` -------------------------------- ### GET /WeatherForecast Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/8_0/VerifyTests.Swagger_IsValidJson_No_Startup_entryPointType=MinimalApp.Program_swaggerRequestUri=v1.verified.txt Retrieves a list of weather forecasts. ```APIDOC ## GET /WeatherForecast ### Description Retrieves a collection of weather forecast objects. ### Method GET ### Endpoint /WeatherForecast ### Response #### Success Response (200) - **date** (string) - The date and time of the forecast. - **temperatureC** (integer) - The temperature in Celsius. - **temperatureF** (integer) - The temperature in Fahrenheit (read-only). - **summary** (string) - A brief description of the weather. #### Response Example [ { "date": "2023-10-27T10:00:00Z", "temperatureC": 20, "temperatureF": 68, "summary": "Sunny" } ] ``` -------------------------------- ### POST /products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/9_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=3.1.verified.txt Creates a new product in the collection. ```APIDOC ## POST /products ### Description Creates a product. ### Method POST ### Endpoint /products ### Request Body - **Product** (object) - Required - Represents a product ### Request Example ```json { "id": "123", "description": "Some product" } ``` ### Response #### Success Response (200) - **Product** (object) - Represents a product ``` -------------------------------- ### POST /products Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/8_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=3.1.verified.txt Creates a new product in the collection. ```APIDOC ## POST /products ### Description Creates a product. ### Method POST ### Endpoint /products ### Request Body - **product** (Product) - Required - Represents a product ### Request Example ```json { "id": "123", "description": "Some product" } ``` ### Response #### Success Response (200) - **product** (Product) - Description of the created product. #### Response Example ```json { "id": "123", "description": "Some product" } ``` ``` -------------------------------- ### GET /Issue3013/Get Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=3.1.verified.txt Retrieves data related to Issue3013. ```APIDOC ## GET /Issue3013/Get ### Description Retrieves data for Issue3013. ### Method GET ### Endpoint /Issue3013/Get ### Response #### Success Response (200) - **schema** - Refers to#/components/schemas/TestResponse ``` -------------------------------- ### Initialize Swagger UI with Configuration Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/WebSites/CustomUIIndex/Swagger/index.html Configures and initializes the Swagger UI bundle using JSON-parsed configuration objects. Ensures the DOM ID, presets, and OAuth redirect URLs are correctly set before rendering. ```javascript window.onload = function() { var configObject = JSON.parse('%(ConfigObject)'); var oauthConfigObject = JSON.parse('%(OAuthConfigObject)'); // Apply mandatory parameters configObject.dom_id = "#swagger-ui"; configObject.presets = [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset]; configObject.layout = "StandaloneLayout"; // If oauth2RedirectUrl isn't specified, use the built-in default if (!configObject.hasOwnProperty("oauth2RedirectUrl")) configObject.oauth2RedirectUrl = (new URL("oauth2-redirect.html", window.location.href)).href; // Begin Swagger UI call region const ui = SwaggerUIBundle(configObject); ui.initOAuth(oauthConfigObject); // End Swagger UI call region window.ui = ui; } ``` -------------------------------- ### GET /files/{name} Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=3.1.verified.txt Retrieves a file by its name. ```APIDOC ## GET /files/{name} ### Description Retrieves a specific file by its name. ### Method GET ### Endpoint /files/{name} ### Parameters #### Path Parameters - **name** (string) - Required - The name of the file to retrieve. ``` -------------------------------- ### GET /WithOpenApi/weatherforecast Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.Swagger_IsValidJson_No_Startup_entryPointType=WebApi.Program_swaggerRequestUri=v1.verified.txt Retrieves a list of weather forecasts. ```APIDOC ## GET /WithOpenApi/weatherforecast ### Description Retrieves a list of weather forecasts. ### Method GET ### Endpoint /WithOpenApi/weatherforecast ### Response #### Success Response (200) - **array** - A list of WeatherForecast objects. ``` -------------------------------- ### Run all tests Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/AGENTS.md Executes the entire test suite. ```bash dotnet test ``` -------------------------------- ### Apply ReDoc Configuration Parameters Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/docs/configure-and-customize-redoc.md Configures various Redoc-specific settings such as spec URL, UI behavior, and display options. ```cs app.UseReDoc(options => { options.SpecUrl("/v1/swagger.json"); options.EnableUntrustedSpec(); options.ScrollYOffset(10); options.HideHostname(); options.HideDownloadButton(); options.ExpandResponses("200,201"); options.RequiredPropsFirst(); options.NoAutoAuth(); options.PathInMiddlePanel(); options.HideLoading(); options.NativeScrollbars(); options.DisableSearch(); options.OnlyRequiredInSamples(); options.SortPropsAlphabetically(); }); ``` -------------------------------- ### GET /files/{name} Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=2.0.verified.txt Retrieves a file by its name. ```APIDOC ## GET /files/{name} ### Description Retrieves a file resource by the specified name. ### Method GET ### Endpoint /files/{name} ### Parameters #### Path Parameters - **name** (string) - Required - The name of the file to retrieve ### Response #### Success Response (200) - **description** (string) - OK ``` -------------------------------- ### GET /unicorns Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=3.1.verified.txt Retrieves a collection of dynamic objects. ```APIDOC ## GET /unicorns ### Description Retrieves a collection of dynamic objects. ### Method GET ### Endpoint /unicorns ### Response #### Success Response (200) - **object** (object) - A collection of dynamic properties. ``` -------------------------------- ### GET /weatherforecast Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.Swagger_IsValidJson_No_Startup_entryPointType=WebApi.Map.Program_swaggerRequestUri=v1.verified.txt Retrieves a list of weather forecasts. ```APIDOC ## GET /weatherforecast ### Description Retrieves a collection of weather forecast objects. ### Method GET ### Endpoint /weatherforecast ### Response #### Success Response (200) - **array** (Forecast) - A list of weather forecast objects. #### Response Example [ { "date": "2023-10-27T10:00:00Z", "temperatureC": 20, "summary": "Mild" } ] ``` -------------------------------- ### Generate OpenAPI Document via CLI Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/docs/configure-and-customize-cli.md Executes the command to generate an OpenAPI JSON file from a specified startup assembly. ```terminal swagger tofile --output [output] [startupassembly] [swaggerdoc] ``` -------------------------------- ### POST /resource Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.SwaggerGen.Test/snapshots/10_0/VerifyTests.ActionWithEndpointNameMetadata.verified.txt Creates a new resource in the system. ```APIDOC ## POST /resource ### Description Creates a new resource. ### Method POST ### Endpoint /resource ### Response #### Success Response (200) - **description** (string) - OK ``` -------------------------------- ### POST /resource Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.SwaggerGen.Test/snapshots/10_0/VerifyTests.ApiParameterDescriptionForBodyIsRequired.verified.txt Creates a new resource in the system. ```APIDOC ## POST /resource ### Description Creates a new resource. ### Method POST ### Endpoint /resource ### Request Body - **body** (object) - Required - The resource data to be created. ### Response #### Success Response (200) - **description** (string) - OK ``` -------------------------------- ### POST /resource Source: https://github.com/domaindrivendev/swashbuckle.aspnetcore/blob/master/test/Swashbuckle.AspNetCore.SwaggerGen.Test/snapshots/10_0/VerifyTests.EndpointMetadataHasSummaryAttribute.verified.txt Creates a new resource in the system. ```APIDOC ## POST /resource ### Description A Test Summary ### Method POST ### Endpoint /resource ### Response #### Success Response (200) - **description** (string) - OK ```