Part 1: How Automation Boosts API Quality – Spring Boot + JWT + Full Test Strategy

In this first installment of our two‑part series, you'll learn how to design and secure a REST API using Spring Boot. We'll cover:

• Building a REST API with Spring Boot and an H2 in‑memory database
• Implementing JWT‑based authentication and role‑based access control
• Generating interactive API documentation with Swagger UI (OpenAPI)
• Performing comprehensive manual testing using curl and Postman

By the end, you'll have a documented, secure API that you can explore and test by hand—laying the groundwork for automated tests in Part 2.

Use Case: Student Management

The API supports the following endpoints:

Method	Endpoint	Description	Secured
POST	/auth/register	Register a new user	❌ No
POST	/auth/login	Login and receive JWT token	❌ No
GET	/students	List all students	✅ Yes
POST	/students	Create a student	✅ Yes
GET	/students/{id}	Get student by ID	✅ Yes
PUT	/students/{id}	Update student details	✅ Yes
DELETE	/students/{id}	Delete a student	✅ Yes

Project Setup

To get started, create a new Spring Boot project and add the necessary dependencies, configuration, and folder structure.

1. Initialize the Project

spring init \
  --name=student-management-api \
  --dependencies=web,security,data-jpa,h2,validation \
  --build=maven \
  com.cb:student-management-api:0.0.1-SNAPSHOT

2. Maven Dependencies

3. Configuration (application.yml)

4. Model

5. DTOs

6. Repository

7. Service

8. Controller

9. Security Config

API Documentation with Swagger UI (OpenAPI)

To provide self‑updating, interactive documentation for your Student Management API, you'll integrate springdoc‑openapi. This gives you both a JSON/YAML OpenAPI spec and a live Swagger UI.

1. Add the Dependency

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.8.8</version>
</dependency>

2. Customize API Metadata (Optional)

3. Default Endpoints

OpenAPI JSON: GET http://localhost:8080/v3/api-docs (API schema in JSON)

Swagger UI: GET http://localhost:8080/swagger-ui.html (UI to explore and test your endpoints)

Panch Prayag

4. Annotate Your Controllers, Models & DTOs

5. Enable JWT "Authorize" in Swagger UI

Panch Prayag

Now Swagger UI shows an Authorize button. Paste Bearer <your-token> there, and all secured endpoints become testable from the browser.

With these steps, you’ll have live, accurate documentation that both developers and automated tools can rely on.

Manual testing using curl

Below are example curl commands to manually test each endpoint of your Student Management API. Replace <TOKEN> with the JWT you obtain from the login step.

1. Register a New User

curl -i -X POST http://localhost:8080/auth/register \
  -H "Content-Type: application/json" \
  -d '{
        "username": "admin",
        "password": "admin123",
        "role": "ADMIN"
      }'

Expected: HTTP/1.1 200 OK (or 201 Created) with body "User registered successfully".

2. Login and Obtain JWT

curl -i -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{
        "username": "admin",
        "password": "admin123"
      }'

Expected: HTTP/1.1 200 OK and response body containing the JWT...

3. Create a New Student (Secured)

curl -i -X POST http://localhost:8080/students \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{
        "name": "Rahul",
        "email": "rahul@mail.com",
        "course": "Physics"
      }'

Expected: HTTP/1.1 201 Created with JSON body of the created student, including its id.

4. List All Students (Secured)

curl -i -X GET http://localhost:8080/students \
  -H "Authorization: Bearer <TOKEN>"

Expected: HTTP/1.1 200 OK with a JSON array of student objects.

5. Get Student by ID (Secured)

curl -i -X GET http://localhost:8080/students/1 \
  -H "Authorization: Bearer <TOKEN>"

Expected: HTTP/1.1 200 OK with JSON of the student whose id is 1.

6. Update a Student (Secured)

curl -i -X PUT http://localhost:8080/students/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{
        "name": "Rahul Verma",
        "email": "rahul.verma@mail.com",
        "course": "Mathematics"
      }'

Expected: HTTP/1.1 200 OK with JSON of the updated student record.

7. Delete a Student (Secured)

curl -i -X DELETE http://localhost:8080/students/1 \
  -H "Authorization: Bearer <TOKEN>"

Expected: HTTP/1.1 204 No Content and an empty body.

Conclusion

In this first part, you’ve successfully built a secure, documented, and fully functional REST API using Spring Boot with JWT authentication, role-based access control, and live API documentation via Swagger UI. You’ve also manually tested all endpoints using curl and verified the core flows.

This sets a solid foundation for the next phase, where we'll automate these flows with unit, integration, contract, E2E, functional, and security tests for complete confidence. Stay tuned for Part 2!

🔗 View the complete project on GitHub: student-management-api