Lesson 4: API Documentation

  Overview

  Learning Material

Resources for this lesson are accessible to you in this repository

The following learning material may be helpful but is not required. Please reference the syllabus for more details.

  Team Assignment

Overview

Purpose: Add documentation to an API
Task: Complete the assignment

For this team activity, your group will be given a Node.js project similar to the one you've been working on and add API documentation to it.

• Download this project as your starting point.
• Examine the code. For this assignment you will only worry about the temple routes.
• Create a new collection in MongoDB called temples.
• Import the temples.json file into your new temples collection.
• Adjust the .env file so that you can successfully run npm start and connect to the database.
• Create a new Swagger file and add documentation for each route you see there. There are many ways to do this, but this swagger-autogen package may be useful.
• Generate a visual UI and living documentation of your swagger.json. There are many ways to do this, but this swagger-ui-express package may be useful.
• Now that you have documented the routes that are existing, talk with your team about what routes are missing. Add these routes to the API documentation.
• Regenerate your swagger.json, and restart your server. Test these routes in the Swagger UI by selecting the "Try it Out" then "Execute" buttons.
• Once completed, review the sample solution below and compare/contrast your findings.
• Use the I-Learn quiz to report your participation in this activity.

  Personal Assignment

Overview

Purpose: Create and publish API documentation.
Task: Complete the assignment.

Learning Objectives

By the end of this assignment the student will be able to do the following:

• Create a Node Project that handles http requests
• Create a collection called "contacts" in MongoDB
• Create a Render project that shows no errors
• Construct API documentation using Swagger that includes the following routes: GET all, GET by id, PUT, Post, and DELETE

Assignment Description

In previous lessons you have written RESTful API routes in Node.js that connect the outside world to a MongoDB database. For this lesson, you will finish your Contacts project. To conclude, you will document your API using Swagger. Below are the steps to complete this task:

• Review the project requirements and grading rubric.
• Create Swagger documentation for this API project. One of the easiest ways to do this is to use the packages mentioned and used in the team activity.
• With your published API (not localhost), test your swagger documentation routes to ensure they work.
• Once completed, push any changes to GitHub and verify changes in Render.
• Your published project must include an "/api-docs" route that has the interactive Swagger GUI.
• Record a brief video demonstration that shows you using the Swagger documentation successfully sending requests to each route. Be sure to use your Render url for this. Also include evidence that your database is being updated. If Render isn't working, you may use localhost, but you still need to submit your Render link in this project submission. Look at the rubric to see how many points will be deducted if you use localhost in this video.
• Push to GitHub.
• Publish to Render.
• Create a brief video demonstrating the functionality of your assignment. Upload it to YouTube (public or unlisted).
• Submit GitHub, Render, and YouTube links in I-Learn.
• Be sure to review the rubric below to see how you will be graded on this assignment.
• EXTRA CREDIT OPPORTUNITY: You can get up to 10% added to your project grade if you display in your video that you successfully used the fronted project referenced below to use your backend API (details in the syllabus).

Full Stack Project Overview

In an effort to help you see how a backend project works within a fullstack project, this React Application was created to work with your Contacts project. It performs all of the api requests/routes that are in your application but with a GUI instead of swagger, or another rest client. As a stretch challenge, try to test your published api with this website. The video below goes into more detail about this, and about 1 extra thing that you'll need to add to your backend api in order for this to work.