انتقل إلى المحتوى
أمين أبوزيد
Englishالعربية
JNR-021

OpenAPI

  • 5 درس
  • 2 ساعة تدريب (تقدير)
ابدأ الوحدة
في هذه الصفحة 8 موضوعات

نص الدروس والتمارين باللغة الإنجليزية، بينما تبقى واجهة الموقع وعناوين الدروس بالعربية.

نظرة عامة

الموضوعات

  • Swagger UI
  • مواصفة OpenAPI
  • أمثلة
  • توثيق الـ API

تعلّم أولًا

2 ساعة تدريب (تقدير)

مخرجات التعلم

  1. Read an OpenAPI document: paths, operations, schemas, responses.
  2. Generate an OpenAPI document from Spring code and serve Swagger UI.
  3. Enrich it with descriptions, examples, and error responses.
  4. Explain code-first vs contract-first and the trade-offs.

الدروس

  1. 01مواصفة OpenAPI
  2. 02توليد التوثيق من Spring (springdoc)
  3. 03الأمثلة واستجابات الأخطاء
  4. 04الكود أولًا مقابل العقد أولًا
  5. 05عرض عملي: من مخرجات springdoc الخام إلى مرجع API قابل للاستخدام

المختبر والتمارين

Lab

JNR-021-LAB1 · Documented Shop API

Outcomes: 1–4 · Time: ~2 h Add springdoc to Shop API and serve Swagger UI. Add descriptions and examples to every operation and DTO, and document the Problem Details error responses. Commit the generated spec file to the repository.

Acceptance: a new developer can call every endpoint using only Swagger UI.

Exercises (assessment: documentation review)

IDOutcomeTask
JNR-021-EX011Given a small OpenAPI YAML, list its paths, operations, schemas, and the response codes of one operation.
JNR-021-EX022Add springdoc to Shop API and open Swagger UI; find the raw JSON spec URL.
JNR-021-EX033Add summary, field descriptions, and a request example to POST /products.
JNR-021-EX043Document 400 and 404 responses on GET /products/{id} and POST /products.
JNR-021-EX054Compare code-first and contract-first for a partner-facing API and choose one with reasons.
JNR-021-EX061, 3Review a deliberately poor spec: find five problems (missing errors, no examples, wrong status, ...).
أظهر الحلول
  • EX01 Check that you listed the paths keys, each HTTP method under them, components/schemas names, and each responses key.
  • EX02 Usually /swagger-ui.html and /v3/api-docs (verify for the springdoc version used).
  • EX03 @Operation(summary = "..."), @Schema(description = "...", example = "Pen") on the record components.
  • EX04 @ApiResponse(responseCode = "404", ...) per operation, referencing the Problem Details schema.
  • EX05 Contract-first suits partner APIs: the design is reviewed and agreed before code; mention the sync risk and a check in CI.
  • EX06 Typical problems: missing error responses, no examples, wrong create status, missing descriptions, undocumented parameters.

Outcome 4 is also checked by quiz Q09 and Q10; the lab criterion covers outcome 2 end to end.

الاختبار

Outcomes: O1 read a spec · O2 generate and serve docs · O3 enrich docs · O4 code-first vs contract-first.

اختبار ذاتي لك: لا توجد درجات، ولا يُحفظ أو يُرسل أي شيء. اختر إجابة ثم تحقق منها، ويمكنك المحاولة مرة أخرى كما تشاء.

  1. 1OpenAPI is:O1
  2. 2Reusable schemas are defined under:O1
  3. 3In a spec, responses are keyed by:O1
  4. 4Swagger UI is:O2
  5. 5springdoc builds the spec from:O2
  6. 6Why add examples?O3
  7. 7Which should be documented?O3
  8. 8Docs say 200 but the code returns 201. This is:O3
  9. 9Contract-first means:O4
  10. 10A benefit of code-first is:O4

الجزء العملي

Six exercises JNR-021-EX01 to EX06 plus the documented-API lab. Pass: at least five exercises and a lab where every endpoint is callable from Swagger UI alone, with the spec committed.

أخطاء شائعة

Undocumented error responses; docs drifting from behavior.

التقييم

Documentation review.

الصلة بالمسار الوظيفي

Contract testing (MID-045) and API management (ARC-025).

اكتب للبحث في المستويات والمراحل والوحدات والدروس.