Build ArticlesController: GET & POST Endpoints

by SLV Team 47 views

Alright, team, let's dive into creating the ArticlesController! This controller will handle requests related to our articles, specifically fetching all articles (GET request for the index) and creating new ones (POST request). This guide will walk you through each step, ensuring you've got a solid foundation for managing articles in our application. Let's get started!

Dependencies

Before we proceed, make sure you've already set up the database table for articles. This controller relies on that table being in place. If you haven't done so yet, go back and complete that step first.

Overview

The goal here is to create a Controller. In the Spring web framework, a Controller acts as the traffic cop, mapping specific URLs (like /api/Articles/all) to the code that generates the response. Think of it as the bridge between user requests and our application's logic.

Step 1: Locate the Controller Directory

First, find the directory where our Java controller source code lives. You'll find it here:

  • src/main/java/edu/ucsb/cs156/example/controllers

Step 2: Choose an Example Controller

Next, we need to pick an example file to base our ArticlesController on. The choice depends on the @Id field in your database table. Refer to the team01 instructions for guidance:

https://ucsb-cs156.github.io/f25/lab/team01.html#two-types-of-id-values-for-an-entity-class

You'll have two options:

  • UCSBDatesController.java (if your database table has a numeric @Id field)
  • UCSBDiningCommonsController.java (if your database table uses a string field as its @Id field)

Keep this example file open – we'll be borrowing code from it.

Step 3: Create ArticlesController.java

In a new window, create a file named ArticlesController.java inside the src/main/java/edu/ucsb/cs156/example/controllers directory.

Now, copy the following from your chosen example file:

  • All of the import statements
  • The top-level class annotations (like @Tag, @RequestMapping, @RestController, and @Slf4j). Adjust these annotations as needed for the ArticlesController.
  • The @Autowired declaration for the repository class associated with your database table. This gives you access to the database. The @Autowired annotation tells Spring Boot to automatically handle the constructor, saving you the trouble. It also lets the code dynamically switch between a real database and a mock database for testing.

Step 4: Add the GET and POST Methods

For now, let's focus on these two methods:

Annotation Purpose
@GetMapping("/all") Retrieves all records from the table and returns them as a JSON array.
@PostMapping("/post") Creates a new row in the table using the data from the input parameters and returns the data as JSON.

Copy these methods with their annotations from the example file to your ArticlesController.java file.

Step 5: Edit Fields and Parameters

Carefully rename the fields, parameters, and variables in the copied methods to match your Articles database table and its corresponding entity. This is a crucial step to ensure the controller interacts correctly with your data model.

Step 6: Test with Swagger

Time to see if things are working! Use Swagger to test your newly created endpoints. Access Swagger-UI through your browser and send requests to /api/Articles/all and /api/Articles/post. Debug any issues until you get the expected results. Pay close attention to the data format required for the POST request.

Step 7: Locate Controller Tests Directory

With interactive testing successful, let's move on to automated tests. Find the directory for controller tests:

  • src/test/java/edu/ucsb/cs156/example/controllers

Find the test file corresponding to the controller you used as a base:

  • UCSBDatesControllerTests.java (if your database table has a numeric @Id field)
  • UCSBDiningCommonsControllerTests.java (if your database table uses a string field as its @Id field)

Keep this test file open; we'll use it as a template.

Step 8: Create ArticlesControllerTests.java

Create a new file named ArticlesControllerTests.java in the src/test/java/edu/ucsb/cs156/example/controllers directory.

Step 9: Copy Test Setup

Copy the following from the test file you identified in step 7:

  • All of the import statements
  • The @WebMvcTest(...) annotation (make sure to change the parameter to ArticlesController.class!) Forgetting this step is a common mistake.
  • The @Import(TestConfig.class) annotation (this stays as is)
  • The @MockBean declaration for the repository associated with your Articles database table. This creates a mock database object using Mockito.
  • The @MockBean declaration for the UserRepository. This is needed for testing user authentication and authorization scenarios.

Step 10: Copy Relevant Tests

Copy only the tests related to the /all (index) and /post (create) methods. These are typically found under comments like:

  • // Tests for GET /api/articles/all
  • // Tests for POST /api/articles/post...

We'll handle tests for other endpoints (like GET for a single record, DELETE, and PUT) in later issues.

Step 11: Achieve 100% Jacoco Coverage

Run the tests using mvn test jacoco:report. Open target/site/jacoco/index.html in your browser to view the coverage report. Iterate and add/modify tests until you achieve 100% line and branch coverage for your ArticlesController.java methods. This ensures that every line of your code is executed during testing.

Step 12: Achieve Full Mutation Coverage with Pitest

Run mutation tests with mvn test pitest:mutationCoverage. Open target/pit-reports/index.html to view the report. Keep iterating until there are no surviving mutations. A surviving mutation means a small change to your code that your tests didn't catch, indicating a potential weakness in your test suite. It's okay if Pitest reports less than 100% line coverage; focus on eliminating surviving mutations.

Acceptance Criteria:

  • [ ] An ArticlesController.java file exists in the correct directory.
  • [ ] ArticlesController.java contains code for a GET /api/Articles/all endpoint that returns a JSON list of all Articles.
  • [ ] ArticlesController.java contains code for a POST /api/Articles/post endpoint to create new Articles.
  • [ ] Swagger-UI endpoints are well-documented.
  • [ ] The POST endpoint correctly adds new records to the database (on localhost).
  • [ ] The GET endpoint correctly displays the new records (on localhost).
  • [ ] The GET and POST endpoints function as expected when deployed to Dokku.
  • [ ] 100% test coverage (Jacoco) for methods in ArticlesController.java.
  • [ ] Full mutation test coverage (Pitest) for methods in ArticlesController.java.

Next Issue

Once you've met all the criteria:

Make a PR: Create a pull request for your branch. Be sure to write a descriptive title and description. Include "Closes #n" (where n is the issue number) in the description.

Ask a teammate to review your PR.

Finally, move this issue from "In Progress" to "In Review."

Review Others' PRs: Help your teammates by reviewing their PRs.

Start Your Next Issue: You can work on these in any order:

  • Add GET (show) endpoint for a single record in Articles table
  • Add PUT (edit) endpoint for a single record in Articles table
  • Add DELETE endpoint for a specific record in Articles table.

Find the next issue on the Kanban board, assign it to yourself, and move it to "In Progress." Create a new branch from the branch of the issue you just finished.

Important: Always create a new branch for each issue, starting from the previous issue's branch. This keeps your code organized and ensures clean pull requests.

Let's get those articles managed, team! Good luck, and happy coding!