Swagger UI

​

What is Swagger UI?

​

Accessing Swagger UI

​

Prerequisites

1. Ensure the application is running on port 8081
2. Open your web browser
3. Navigate to the Swagger UI endpoint

​

URL Endpoints

http://localhost:8081/swagger-ui/index.html

http://localhost:8081/v3/api-docs

​

Swagger Configuration

​

API Information

​

Available Servers

http://localhost:8081

http://books:8081

​

Using Swagger UI

​

1. Explore Available Endpoints

• auth-user-controller: Authentication endpoints (login, register)
• book-controller: Book management endpoints
• user-controller: User management endpoints

• HTTP method (GET, POST, PUT, DELETE)
• Endpoint path
• Brief description
• Required authentication

​

2. Authentication with JWT

​

Step 1: Register or Login

1. Expand the auth-user-controller section
2. Click on POST /api/v1/auth/login or POST /api/v1/auth/register
3. Click “Try it out”
4. Enter your credentials in the request body:

{
  "username": "your-username",
  "password": "your-password"
}

5. Click “Execute”
6. Copy the JWT token from the response

​

Step 2: Authorize Swagger UI

1. Click the “Authorize” button (lock icon) at the top of the page
2. In the “Security token” dialog, enter:
   Bearer <your-jwt-token>
   
3. Click “Authorize”
4. Click “Close”

​

3. Testing Endpoints

​

Making a Request

1. Expand an endpoint by clicking on it
2. Click “Try it out” button
3. Fill in parameters:
   • Path parameters (e.g., id)
   • Query parameters (e.g., page, size)
   • Request body (for POST/PUT requests)
4. Click “Execute”
5. View the response below

​

Response Information

• Response code: HTTP status (200, 201, 404, etc.)
• Response body: JSON response data
• Response headers: HTTP headers returned
• Request duration: Time taken to execute

​

4. Understanding Request/Response Schemas

• Request Body Schema: Expected JSON structure for POST/PUT requests
• Response Schema: Structure of successful responses
• Required Fields: Fields marked as required with an asterisk (*)
• Data Types: Type information for each field (string, integer, UUID, etc.)

​

Swagger UI Features

​

Endpoint Categories

​

HTTP Methods

​

Models/Schemas

• AuthLoginRequest: Login credentials
• AuthLoginResponse: Login response with JWT token
• AuthRegisterRequest: Registration data
• BookRequest: Book creation/update data
• BookResponse: Book resource representation
• UserRequest: User creation/update data
• UserResponse: User resource representation
• CustomPageableResponse: Pagination wrapper

​

Common Use Cases

​

Example 1: Register and Login

1. Navigate to POST /api/v1/auth/register
2. Try it out with:
   {
     "username": "testuser",
     "password": "SecurePass123",
     "email": "[email protected]",
     "firstName": "Test",
     "lastName": "User"
   }
   
3. Execute and receive your JWT token
4. Use the token to authorize (see Authentication section above)

​

Example 2: List All Books

1. Ensure you’re authenticated (see Authentication section)
2. Navigate to GET /api/v1/books/findAll
3. Try it out
4. Optionally set parameters:
   • page: 0 (first page)
   • size: 10 (items per page)
   • title: filter by book title
   • author: filter by author
   • gender: filter by genre
5. Execute to see paginated results

​

Example 3: Create a New Book

1. Ensure you’re authenticated
2. Navigate to POST /api/v1/books/create
3. Try it out with:
   {
     "title": "Sample Book",
     "author": "John Doe",
     "isbn": "978-3-16-148410-0",
     "gender": "Fiction",
     "publisher": "Sample Publisher",
     "publicationYear": 2024
   }
   
4. Execute and receive the created book with its UUID

​

Example 4: Add Book to User Collection

1. Ensure you’re authenticated
2. Get your user ID from GET /api/v1/users/logged
3. Get a book ID from GET /api/v1/books/findAll
4. Navigate to POST /api/v1/users/{userId}/books/{bookId}
5. Enter both UUIDs in the path parameters
6. Execute to add the book to your collection

​

Security Features

​

JWT Token Authentication

• Scheme Type: HTTP
• Security Scheme: Bearer
• Token Format: JWT (JSON Web Token)
• Header: Authorization
• Location: Header

​

Token Expiration

1. Login again to get a new token
2. Re-authorize Swagger UI with the new token
3. Continue testing

​

Tips and Best Practices

​

Troubleshooting

​

Common Issues

​

Getting Help

1. Check the response body for detailed error messages
2. Verify your request matches the schema requirements
3. Ensure all required fields are provided
4. Check that UUIDs are in the correct format

​

Next Steps