Third Party Documentation
Tutorial: Exploring Swagger UI with ASP.NET 8.0
Introduction to Swagger UI
What is Swagger UI?
Swagger UI is a tool that helps you visualize and interact with APIs built using ASP.NET 8.0, without writing any code. It creates a webpage that describes how your API works and lets you try out API calls directly from your browser.
Why Use Swagger UI?
- Easy to Understand: Presents API functions in a clear and interactive format.
- No Code Required: No need to write any code to test API behavior.
- Real-Time Testing: Allows sending requests and receiving responses in real-time.
How to Access Swagger UI
You can access Swagger UI by going to /swagger.
Navigating Swagger UI
Once you open Swagger UI, you'll see a list of available API endpoints. Each endpoint includes:
- HTTP Method: Type of request (GET, POST, etc.).
- Path: URL pattern that the API responds to.
- Description: Brief details about what the endpoint does.
Handling API Versions in Swagger UI
- Version Selector: Adjusts the API path based on the chosen version.
- Version Pattern: Follows a format like
vYYMM (e.g., v3006 for June 2030).
- Default to Latest: Accessing
/api/v0/ redirects to the latest version.
Making Requests and Understanding Responses
GET Requests
- Find the GET method in the list of endpoints.
- Click
Try it out, then Execute to send a request.
POST Requests
- Select a POST endpoint and provide the required data.
- Click
Execute to send the request.
PUT, PATCH, and DELETE Requests
- PUT: Used to update existing data.
- PATCH: Partially updates existing data.
- DELETE: Removes existing data.
Testing Requests in Your Browser
You can manually test GET requests by entering the request URL in your browserโs address bar, e.g., /api/v0/Activity/GetMany.
Basic Parameter Inclusion
- Required Parameters: Must be provided for some endpoints (e.g.,
FileID for document retrieval).
- Optional Parameters: Modify responses without being mandatory (e.g.,
NumberOfRecords and RecordOffset for pagination).
Adding Multiple Parameters
Use the & symbol to separate multiple query parameters, e.g.,
/api/v0/Activity/GetMany?NumberOfRecords=10&RecordOffset=2
Complex Filters
For advanced filtering:
/api/v0/Contact/GetMany?NumberOfRecords=100&Filter[0].CityId=5963&Filter[0].territoryID=55
Specialized Endpoints
- Documents Get:
/api/v0/Documents/Get?FileID=12345 retrieves a file in BASE64 format.
- Dictionary Get: Retrieves field names in a specific language, e.g.,
/api/v0/Dictionary/Get?Resource=/api/v0/Activity/GetMany&Language=French.
Continuing Education
Enhance your skills through the following resources: