Chitkara University Students: Writing API Documentation Recruiters Actually Open

Recruiters open API documentation that answers three questions within a minute: what does this do, how do I run it, and what does a real request look like. Put a short README on top, an OpenAPI file underneath, and a copy-pasteable example for every endpoint, then score the result with the five-minute rubric below before you share it.

Why a recruiter opens your README and skips your code

A person screening backend portfolios may look at dozens of repositories in a sitting. They rarely clone the code first. They read the top of the README, scroll for a request example, and check whether the project looks finished. If the first screen is a project title and a line saying “backend project using Flask”, there is nothing to judge, so they move on.

Good documentation is also evidence of engineering habits: you name things consistently, you think about failure cases, and you can explain a system to someone who did not build it. That is much of what a backend role involves day to day.

This guide gives you a README skeleton, an OpenAPI skeleton, example requests and responses, a worked illustration, and a rubric. The material is aimed at a small Python API (FastAPI or Flask) of the kind built in a two-week learning sprint.

The README skeleton for a Python API, section by section

Use this order. It front-loads what a skimming reader needs and pushes setup detail lower down.

1. One-sentence purpose. “A REST API for managing library book loans, built with FastAPI and SQLite.” Name the problem, the stack and the data store.
2. Quick start (under 6 commands). Clone, create a virtual environment, install, run, open the docs URL.
3. One working request and response. A single curl command and its output, visible without scrolling much.
4. Endpoint table. Method, path, purpose, auth requirement.
5. Configuration. Environment variables, their meaning, and a safe example value.
6. Error format. One consistent shape for all errors.
7. Tests and how to run them. One command.
8. Design notes. Three to five bullets on decisions: why SQLite, why token auth, known limits.

README template you can copy (illustrative)

# Library Loans API

REST API for tracking book loans. Python 3.11, FastAPI, SQLite.

## Quick start

git clone <your-repo-url>
cd library-loans-api
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload

Interactive docs: http://127.0.0.1:8000/docs

## Try it

curl -X POST http://127.0.0.1:8000/loans \
  -H "Content-Type: application/json" \
  -H "X-API-Key: demo-key" \
  -d '{"book_id": 12, "member_id": 4, "days": 14}'

Response (201 Created):

{"id": 101, "book_id": 12, "member_id": 4,
 "due_date": "2026-12-01", "status": "active"}

## Endpoints

| Method | Path | Purpose | Auth |
|--------|------|---------|------|
| POST | /loans | Create a loan | Yes |
| GET | /loans/{id} | Fetch one loan | Yes |
| GET | /loans | List loans (filter by status) | Yes |
| PATCH | /loans/{id}/return | Mark returned | Yes |

## Errors

{"error": {"code": "book_unavailable",
 "message": "Book 12 is already on loan."}}

## Configuration

API_KEY   key expected in X-API-Key (example: demo-key)
DB_URL    SQLite path (default: sqlite:///loans.db)

## Tests

pytest -q

The values above are made up for illustration. Replace them with output you have actually produced from your own running project, and never publish real keys or passwords.

OpenAPI skeleton: the machine-readable half

FastAPI generates an OpenAPI document automatically, but the generated version is only as good as the descriptions and examples you supply. If you use Flask, you can write the YAML by hand or use a plugin. Either way, the file should contain summaries, typed schemas, examples and every error response you actually return.

OpenAPI fragment for one endpoint (illustrative)

openapi: 3.0.3
info:
  title: Library Loans API
  version: 1.0.0
  description: Track book loans. Auth via X-API-Key header.
paths:
  /loans:
    post:
      summary: Create a loan
      description: Fails with 409 if the book is already on loan.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoanCreate'
            example:
              book_id: 12
              member_id: 4
              days: 14
      responses:
        '201':
          description: Loan created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Loan'
              example:
                id: 101
                book_id: 12
                member_id: 4
                due_date: '2026-12-01'
                status: active
        '409':
          description: Book unavailable
          content:
            application/json:
              example:
                error:
                  code: book_unavailable
                  message: Book 12 is already on loan.
        '422':
          description: Validation error
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
  schemas:
    LoanCreate:
      type: object
      required: [book_id, member_id]
      properties:
        book_id: {type: integer}
        member_id: {type: integer}
        days: {type: integer, minimum: 1, maximum: 30, default: 14}

What to document for each endpoint

A worked illustration: rewriting a weak README in four edits

This is an invented before-and-after, not a real student project.

Before: The README says “Library API. Run main.py. Endpoints: /loans, /books.” There is no example, no setup steps and no error information.

Edit 1, purpose line. Replace the title-only opening with: “REST API for tracking book loans. Python 3.11, FastAPI, SQLite.”

Edit 2, quick start. Replace “Run main.py” with the venv, install and uvicorn commands, plus the docs URL. A reader can now see something running in about a minute.

Edit 3, one real request. Add the curl call and the 201 response. Now the reader sees field names, types and the date format without opening code.

Edit 4, errors. Add the 409 example and state that every error uses the same envelope. This signals that you designed the failure paths rather than letting the framework surprise you.

The four edits take well under an hour once the API works, and they change what the repository communicates. Before, it says “a script exists”. After, it says “a service someone can use”.

The five-minute reviewer’s rubric for API documentation

Ask a classmate to open your repository cold and score it with a timer running. Each row is 0, 1 or 2 points. Total out of 20.

Reading the score

• 16 to 20: ready to link from a CV or LinkedIn.
• 10 to 15: usable, but fix every row scored 0 first, starting with rows 2 and 3.
• Below 10: a reader cannot run or understand the project quickly; rewrite the top of the README before anything else.

If the reviewer cannot get a response from your API within five minutes, treat that as a failure regardless of the total.

Chitkara University students: turning API docs into portfolio evidence

Chitkara University’s site navigation lists an Engineering & Technology programmes section and online MBA tracks in Data Science & AI and Cyber Security, and its Career Advancement Services page describes industry-ready training, skill development and placement support in its meta description. A separate admissions page excerpt mentions on-campus internship portals and corporate connect programmes; that is marketing wording rather than a policy document, so check the current page before relying on it.

For a backend student, the practical meaning is simple: whatever support exists, a recruiter or mentor will still judge you on artefacts you can show. A documented API repository is one you can attach to a placement-cell profile, an internship application or a project report without needing anyone to explain it.

What could not be confirmed is how project work, internships or industrial training are regulated for your programme: duration, evaluation, documents required, or whether an online internship is accepted. Those rules may also differ by school or scheme year, so do not assume them. Also confirm which campus’s pages apply to you, since the university’s navigation links to more than one portal.

Five steps to verify what applies to your programme

1. Ask your department or training coordinator, in writing, for the current internship or project-work guidelines for your scheme year.
2. Ask whether an online internship is accepted and what proof (offer letter, certificate, report format) is required.
3. Ask the Career Advancement Services office what profile format or portfolio links they want students to submit.
4. Check whether documentation, a GitHub link or a demo is assessed in your project-evaluation rubric.
5. Keep the reply emails with your project records so they can be produced later.

Fitting the documentation work into a 14-day internship

The free two-week online internship at CareerSwami offers a free offer letter and a free completion certificate after successful completion, across 26 tracks. If you pick a Python backend track, build the documentation alongside the code instead of saving it for the end. This plan is a suggestion, not a prescribed syllabus.

Documentation slips that make a README look unfinished

• Examples that were never run. Paste output from your actual server. A mismatch between the example and real behaviour is worse than no example.
• Secrets in the repository. Use placeholder values and an .env.example file; keep real keys out of version control history.
• Setup steps that assume your laptop. Test them in a fresh virtual environment, ideally on another machine.
• Undocumented status codes. If the code returns 409, the docs should say so.
• Inconsistent field names. Choose snake_case or camelCase and keep it everywhere, including error bodies.
• A stale OpenAPI file. If the file is hand-written, regenerate or review it after every route change.

Frequently Asked Questions

Should I write the OpenAPI file by hand or generate it?

With FastAPI, generate it and improve it by adding summaries, descriptions and examples to your route and schema definitions. With Flask, either write the YAML by hand or use a library that builds it from your code. Whichever you choose, read the final file to check it matches real behaviour.

How long should an API README be?

Long enough to cover the eight sections, short enough that the first request example appears near the top. Move detail such as architecture diagrams to a separate docs folder and link to it.

Do recruiters really run the quick start?

Some do, many do not. Treat the quick start as proof that the project is reproducible, and make the curl example and sample response readable without running anything.

Is the auto-generated /docs page enough?

It helps, but it is not a README. A reader on GitHub never sees it unless they run the server. Include a short screenshot or the key examples in the README itself.

What should I put in the error section if my API is tiny?

State the single error shape and show two or three realistic cases, such as a missing field, an unknown ID and a conflict. A small API with clear errors reads better than a large one with none.

Can I use this documentation for my university project report?

The content is reusable, but your department sets the report format and evaluation. Ask your project coordinator what structure and documents are required, and adapt these sections to fit.

How do I know my rubric score is honest?

Do not score your own work. Hand the repository link to someone who has not seen the project, give them five minutes, and do not answer questions while they work. Every question they ask marks a gap in the docs.

Does a completion certificate replace good documentation?

No. A certificate shows you finished an internship; the documented repository shows what you can build. Use both together when you apply, and describe the certificate as exactly what it is: a free completion certificate from a two-week online internship.

Related Python & Backend Engineering guides

• Central University of Gujarat Students: Asking Better Questions of Your Backend Mentor
• Madhav University Students: Caching and Performance Basics for a Backend Internship Demo
• Sharnbasva University Students: Learning Backend Python on a Phone and Shared Laptop
• All Python & Backend Engineering internship guides