توثيق API باستخدام Swagger و OpenAPI

openapi: "3.0.3"
info:
  title: مدونة API
  description: واجهة إدارة المقالات
  version: "1.0.0"
servers:
  - url: https://api.example.com/v1
paths:
  /articles:
    get:
      summary: قائمة المقالات
      parameters:
        - name: page
          in: query
          schema: { type: integer, default: 1 }
      responses:
        "200":
          description: نجاح
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Article"
components:
  schemas:
    Article:
      type: object
      required: [id, title]
      properties:
        id: { type: integer }
        title: { type: string }
        body: { type: string }

import swaggerJsdoc from "swagger-jsdoc";
import swaggerUi from "swagger-ui-express";

const options = {
  definition: {
    openapi: "3.0.3",
    info: { title: "مدونة API", version: "1.0.0" },
  },
  apis: ["./routes/*.js"],
};

const swaggerSpec = swaggerJsdoc(options);
app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerSpec));

/**
 * @openapi
 * /articles:
 *   get:
 *     summary: قائمة المقالات
 *     responses:
 *       200:
 *         description: نجاح
 */
router.get("/articles", getArticles);

import request from "supertest";
import app from "../app.js";

test("GET /articles يعيد 200", async () => {
  const res = await request(app).get("/articles");
  expect(res.status).toBe(200);
  expect(Array.isArray(res.body)).toBe(true);
});

test("POST /articles بدون مصادقة يعيد 401", async () => {
  const res = await request(app)
    .post("/articles")
    .send({ title: "اختبار" });
  expect(res.status).toBe(401);
});