API ஆவணப்படுத்தல் பரிணாமம்: ஓபன்ஏபிஐ விவரக்குறிப்புக்கான ஒரு விரிவான வழிகாட்டி

இன்றைய அதி-இணைக்கப்பட்ட டிஜிட்டல் உலகில், பயன்பாட்டு நிரலாக்க இடைமுகங்கள் (APIs) தான் நமது மென்பொருள் மற்றும் சேவைகளை ஒன்றாக இணைக்கும் கண்ணுக்குத் தெரியாத இழைகளாகும். அவை மொபைல் பேங்கிங் முதல் சமூக ஊடக பதிவுகள் வரை அனைத்தையும் இயக்கும் நவீன டிஜிட்டல் பொருளாதாரத்தின் இயந்திரமாகும். ஆனால் ஏபிஐ-களின் எண்ணிக்கை வெடிக்கும்போது, ஒரு முக்கியமான சவால் எழுகிறது: டெவலப்பர்கள், அமைப்புகள் மற்றும் நிறுவனங்கள் எவ்வாறு திறம்பட மற்றும் தெளிவின்மையின்றி தொடர்பு கொள்ள முடியும்? உலகின் ஒரு பகுதியில் உருவாக்கப்பட்ட ஒரு ஏபிஐ, மற்றொரு பகுதியில் உள்ள ஒரு சேவையால் தடையின்றி பயன்படுத்தப்படுவதை நாம் எப்படி உறுதி செய்வது?

அதற்கான பதில் ஒரு பொதுவான மொழியில், அதாவது மனிதர்களும் இயந்திரங்களும் புரிந்து கொள்ளக்கூடிய வகையில் ஒரு ஏபிஐ-யின் திறன்களை விவரிக்கும் ஒரு உலகளாவிய ஒப்பந்தத்தில் உள்ளது. இதுவே ஓபன்ஏபிஐ விவரக்குறிப்பின் (OAS) பங்கு. வெறும் ஆவணப்படுத்தலை விட, OAS என்பது ரெஸ்ட்ஃபுல் ஏபிஐ-களை வடிவமைப்பதற்கும், உருவாக்குவதற்கும், ஆவணப்படுத்துவதற்கும் மற்றும் பயன்படுத்துவதற்கும் ஒரு அடிப்படைத் தரமாகும். இந்த வழிகாட்டி உங்களை ஓபன்ஏபிஐ விவரக்குறிப்பின் ஆழத்திற்கு அழைத்துச் செல்லும், அது என்ன, ஏன் முக்கியம், மற்றும் சிறந்த, மேலும் கூட்டுழைப்புடன் கூடிய டிஜிட்டல் தயாரிப்புகளை உருவாக்க அதை நீங்கள் எவ்வாறு பயன்படுத்தலாம் என்பதை ஆராயும்.

ஓபன்ஏபிஐ விவரக்குறிப்பு என்றால் என்ன? ஏபிஐ-களுக்கான ஒரு உலகளாவிய மொழி

அதன் மையத்தில், ஓபன்ஏபிஐ விவரக்குறிப்பு என்பது ரெஸ்ட்ஃபுல் ஏபிஐ-களுக்கான ஒரு நிலையான, மொழி-சார்பற்ற இடைமுக விளக்கமாகும். இது உங்கள் ஏபிஐ-யின் முழு கட்டமைப்பையும் ஒரே கோப்பில், பொதுவாக YAML அல்லது JSON இல் எழுத அனுமதிக்கிறது. இதை ஒரு கட்டிடத்திற்கான விரிவான வரைபடமாக நினைத்துப் பாருங்கள்; எந்தவொரு கட்டுமானப் பணிகளும் தொடங்குவதற்கு முன்பு, அந்த வரைபடம் ஒவ்வொரு அறையையும், ஒவ்வொரு வாசலையும், ஒவ்வொரு மின் இணைப்பையும் கோடிட்டுக் காட்டுகிறது. இதேபோல், ஒரு ஓபன்ஏபிஐ ஆவணம் விவரிக்கிறது:

• கிடைக்கக்கூடிய அனைத்து எண்ட்பாயிண்ட்கள் அல்லது பாதைகள் (எ.கா., /users, /products/{id}).
• ஒவ்வொரு எண்ட்பாயிண்டிலும் கிடைக்கக்கூடிய செயல்பாடுகள் (HTTP முறைகள்) (எ.கா., GET, POST, PUT, DELETE).
• ஒவ்வொரு செயல்பாட்டிற்குமான அளவுருக்கள், ஹெடர்கள் மற்றும் கோரிக்கை உள்ளடக்கங்கள்.
• பல்வேறு HTTP நிலைக் குறியீடுகள் உட்பட, ஒவ்வொரு செயல்பாட்டிற்குமான பதில் பொருட்களின் கட்டமைப்பு.
• அங்கீகார முறைகள், தொடர்புத் தகவல், உரிமம், பயன்பாட்டு விதிமுறைகள் மற்றும் பிற முக்கியமான மெட்டாடேட்டா.

ஒரு சுருக்கமான வரலாறு: ஸ்வேகரிலிருந்து ஓபன்ஏபிஐ வரை

ஓபன்ஏபிஐ உடன் "ஸ்வேகர்" என்ற சொல் ஒன்றுக்கொன்று மாற்றாகப் பயன்படுத்தப்படுவதை நீங்கள் கேள்விப்பட்டிருக்கலாம். அவற்றின் உறவைப் புரிந்துகொள்வது அவசியம். இந்த விவரக்குறிப்பு 2010 இல் ஸ்வேகர் விவரக்குறிப்பாகத் தொடங்கியது, இது ரெவெர்பில் டோனி டாம் என்பவரால் உருவாக்கப்பட்டது. இது பெரும் புகழ் பெற்றதால், 2015 இல் லினக்ஸ் அறக்கட்டளைக்கு வழங்கப்பட்டு, ஓபன்ஏபிஐ விவரக்குறிப்பு எனப் பெயர் மாற்றப்பட்டது. கூகிள், மைக்ரோசாப்ட் மற்றும் ஐபிஎம் உள்ளிட்ட தொழில் தலைவர்களின் கூட்டமைப்பான ஓபன்ஏபிஐ முன்முயற்சியின் கீழ் இது ஒரு உண்மையான திறந்த தரநிலையாக நிறுவப்பட்டது.

இன்று, ஸ்வேகர் என்பது ஓபன்ஏபிஐ விவரக்குறிப்புடன் செயல்படும் சக்திவாய்ந்த திறந்த மூல மற்றும் தொழில்முறை கருவிகளின் தொகுப்பைக் குறிக்கிறது, அதாவது ஊடாடும் ஆவணங்களை உருவாக்குவதற்கான ஸ்வேகர் UI மற்றும் விவரக்குறிப்பை எழுதுவதற்கான ஸ்வேகர் எடிட்டர் போன்றவை.

ஒரு ஓபன்ஏபிஐ ஆவணத்தின் முக்கிய கூறுகள்

ஒரு ஓபன்ஏபிஐ ஆவணம் குறிப்பிட்ட புலங்களின் தொகுப்புடன் கட்டமைக்கப்பட்டுள்ளது. இது முதலில் பார்க்கும்போது சற்று அச்சுறுத்தலாகத் தோன்றினாலும், இது தர்க்கரீதியாக ஒழுங்கமைக்கப்பட்டுள்ளது. ஓபன்ஏபிஐ 3.x ஆவணத்தின் முக்கிய கட்டமைப்புத் தொகுதிகளை, அதன் மனிதர்களுக்கு எளிதில் படிக்கக்கூடிய தன்மைக்காக YAML ஐப் பயன்படுத்தி உடைத்துப் பார்ப்போம்.

1. `openapi` மற்றும் `info` ஆப்ஜெக்ட்கள்: அடிப்படைகள்

ஒவ்வொரு ஓபன்ஏபிஐ ஆவணமும் ஒரு பதிப்பு எண் மற்றும் அத்தியாவசிய மெட்டாடேட்டாவுடன் தொடங்குகிறது.

• openapi: பயன்படுத்தப்படும் ஓபன்ஏபிஐ விவரக்குறிப்பின் பதிப்பைக் குறிப்பிடும் ஒரு சரம் (எ.கா., "3.0.3" அல்லது "3.1.0"). இது கட்டாயமாகும்.
• info: ஏபிஐ பற்றிய மெட்டாடேட்டாவை வழங்கும் ஒரு ஆப்ஜெக்ட். இது title, ஒரு description, உங்கள் ஏபிஐ-க்கான ஒரு version எண் (OAS பதிப்பு அல்ல), மற்றும் contact மற்றும் license போன்ற விருப்ப புலங்களை உள்ளடக்கியது. இந்தத் தகவல் கண்டுபிடிப்பு மற்றும் ஆளுகைக்கு முக்கியமானது.

உதாரணம்:

openapi: 3.0.3
info:
  title: Global Book Catalog API
  description: An API for accessing a catalog of books from around the world.
  version: 1.0.0
  contact:
    name: API Support Team
    url: http://www.example.com/support
    email: support@example.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html

2. `servers` வரிசை: உங்கள் ஏபிஐ-ஐ எங்கே கண்டுபிடிப்பது

servers வரிசையானது உங்கள் ஏபிஐ-க்கான அடிப்படை URL-களைக் குறிப்பிடுகிறது. டெவலப்மெண்ட், ஸ்டேஜிங் மற்றும் புரொடக்ஷன் போன்ற வெவ்வேறு சூழல்களுக்கு நீங்கள் பல சேவையகங்களை வரையறுக்கலாம். இது கருவிகள் எளிதாக சூழல்களுக்கு இடையில் மாற அனுமதிக்கிறது.

உதாரணம்:

servers:
  - url: https://api.example.com/v1
    description: Production Server
  - url: https://staging-api.example.com/v1
    description: Staging Server

3. `paths` ஆப்ஜெக்ட்: ஏபிஐ-யின் இதயம்

இங்கேதான் உங்கள் ஏபிஐ-யின் எண்ட்பாயிண்ட்களை நீங்கள் வரையறுக்கிறீர்கள். paths ஆப்ஜெக்ட் அனைத்து தனிப்பட்ட URL பாதைகளையும் வைத்திருக்கிறது. ஒவ்வொரு பாதை உருப்படியும் அந்தப் பாதையில் செய்யக்கூடிய HTTP செயல்பாடுகளை (get, post, put, delete, முதலியன) விவரிக்கிறது.

ஒவ்வொரு செயல்பாட்டிற்குள்ளும், நீங்கள் இது போன்ற விவரங்களை வரையறுக்கிறீர்கள்:

• summary மற்றும் description: செயல்பாடு என்ன செய்கிறது என்பதற்கான ஒரு குறுகிய மற்றும் நீண்ட விளக்கம்.
• operationId: ஒரு தனித்துவமான அடையாளங்காட்டி, பெரும்பாலும் குறியீடு உருவாக்குபவர்களால் பயன்படுத்தப்படுகிறது.
• parameters: உள்ளீட்டு அளவுருக்களின் ஒரு வரிசை, இது பாதை, வினவல் சரம், ஹெடர் அல்லது குக்கீயில் இருக்கலாம்.
• requestBody: கோரிக்கையுடன் அனுப்பப்படும் பேலோடின் விளக்கம் (எ.கா., ஒரு புதிய பயனருக்கான JSON).
• responses: செயல்பாட்டின் சாத்தியமான விளைவுகள், HTTP நிலைக் குறியீடுகளால் வரையறுக்கப்படுகின்றன (வெற்றிக்கு 200, கண்டுபிடிக்கப்படாததற்கு 404, சேவையகப் பிழைக்கு 500 போன்றவை). ஒவ்வொரு பதிலும் அதன் சொந்த விளக்கம் மற்றும் உள்ளடக்க ஸ்கீமாவைக் கொண்டிருக்கலாம்.

4. `components` ஆப்ஜெக்ட்: மீண்டும் பயன்படுத்தக்கூடிய கட்டமைப்புத் தொகுதிகள்

மீண்டும் மீண்டும் செய்வதைத் தவிர்க்க (DRY கோட்பாட்டைப் பின்பற்றி), ஓபன்ஏபிஐ components ஆப்ஜெக்ட்டை வழங்குகிறது. இது ஒரு சக்திவாய்ந்த அம்சமாகும், அங்கு நீங்கள் மீண்டும் பயன்படுத்தக்கூடிய கூறுகளை வரையறுத்து அவற்றை உங்கள் விவரக்குறிப்பு முழுவதும் $ref சுட்டிகளைப் பயன்படுத்தி குறிப்பிடலாம்.

• `schemas`: JSON ஸ்கீமாவுடன் இணக்கமான வடிவத்தைப் பயன்படுத்தி உங்கள் தரவு மாதிரிகளை இங்கே வரையறுக்கிறீர்கள். உதாரணமாக, நீங்கள் ஒரு User ஆப்ஜெக்ட்டை id, name, மற்றும் email போன்ற பண்புகளுடன் ஒருமுறை வரையறுத்து, பின்னர் ஒரு பயனர் ஆப்ஜெக்ட்டைப் பயன்படுத்தும் ஒவ்வொரு கோரிக்கை அல்லது பதிலிலும் அதைக் குறிப்பிடலாம்.
• `parameters`: ஒரு userId பாதை அளவுரு அல்லது ஒரு limit வினவல் அளவுரு போன்ற பொதுவான அளவுருக்களை வரையறுத்து, அவற்றை வெவ்வேறு செயல்பாடுகளில் மீண்டும் பயன்படுத்தவும்.
• `responses`: 404NotFound அல்லது 401Unauthorized போன்ற நிலையான பதில்களை வரையறுத்து, தேவையான இடங்களில் அவற்றைப் பயன்படுத்தவும்.
• `securitySchemes`: உங்கள் ஏபிஐ உடன் கிளையண்டுகள் எவ்வாறு அங்கீகரிக்கிறார்கள் என்பதை வரையறுக்கவும். ஓபன்ஏபிஐ API கீகள், HTTP Basic மற்றும் Bearer அங்கீகாரம், மற்றும் OAuth 2.0 உள்ளிட்ட பல்வேறு திட்டங்களை ஆதரிக்கிறது.

5. `security` ஆப்ஜெக்ட்: அங்கீகாரத்தைப் பயன்படுத்துதல்

கூறுகளில் உங்கள் securitySchemes-ஐ வரையறுத்தவுடன், security ஆப்ஜெக்ட் அவற்றைப் பயன்படுத்தப் பயன்படுகிறது. நீங்கள் முழு ஏபிஐ-க்கும் உலகளாவிய ரீதியாக பாதுகாப்பைப் பயன்படுத்தலாம் அல்லது ஒவ்வொரு செயல்பாட்டிற்கும் தனித்தனியாகப் பயன்படுத்தலாம், இது பொது மற்றும் பாதுகாக்கப்பட்ட எண்ட்பாயிண்ட்களின் கலவையை அனுமதிக்கிறது.

உங்கள் நிறுவனம் ஏன் ஓபன்ஏபிஐ-ஐ ஏற்றுக்கொள்ள வேண்டும்: வணிக மற்றும் தொழில்நுட்ப நன்மைகள்

ஓபன்ஏபிஐ விவரக்குறிப்பை ஏற்றுக்கொள்வது ஒரு தொழில்நுட்பத் தேர்வு மட்டுமல்ல; இது முழு மென்பொருள் மேம்பாட்டு வாழ்க்கைச் சுழற்சியிலும் செயல்திறன், ஒத்துழைப்பு மற்றும் தரத்தை இயக்கும் ஒரு மூலோபாய முடிவாகும்.

டெவலப்பர்களுக்கு: உண்மையின் ஒற்றை ஆதாரம்

• தெளிவான தொடர்பு: OAS ஆனது ஃப்ரண்ட்எண்ட் மற்றும் பேக்எண்ட் குழுக்களுக்கு இடையே, அல்லது சேவை தயாரிப்பாளர்கள் மற்றும் நுகர்வோருக்கு இடையே ஒரு தெளிவான ஒப்பந்தத்தை வழங்குகிறது. இது இணையான மேம்பாட்டை செயல்படுத்துகிறது, ஏனெனில் இரு தரப்பினரும் மற்றவர் முடிக்கும் வரை காத்திருக்காமல் ஒப்புக்கொள்ளப்பட்ட விவரக்குறிப்பிலிருந்து பணியாற்ற முடியும்.
• தானியங்கு குறியீடு உருவாக்கம்: OpenAPI Generator போன்ற கருவிகளைக் கொண்டு, டெவலப்பர்கள் தானாகவே டஜன் கணக்கான மொழிகளில் (Java, Python, JavaScript, Go, ইত্যাদি) கிளையன்ட் SDK-களையும் சர்வர் ஸ்டப்களையும் உருவாக்க முடியும். இது பெரும் அளவிலான பாய்லர்பிளேட் குறியீட்டை நீக்கி, கைமுறைப் பிழைகளின் வாய்ப்பைக் குறைக்கிறது.
• மேம்படுத்தப்பட்ட உள்நுழைவு: புதிய டெவலப்பர்கள், காலாவதியான விக்கிகள் அல்லது மூலக் குறியீட்டைப் படிப்பதற்குப் பதிலாக, ஓபன்ஏபிஐ கோப்பிலிருந்து நேரடியாக உருவாக்கப்பட்ட ஊடாடும் ஆவணங்களை ஆராய்வதன் மூலம் மிக வேகமாகப் பழகிக் கொள்ள முடியும்.

தயாரிப்பு மேலாளர்கள் மற்றும் கட்டிடக் கலைஞர்களுக்கு: வடிவமைப்பு மற்றும் ஆளுகை

• API-முதல் வடிவமைப்பு: ஓபன்ஏபிஐ என்பது API-முதல் அணுகுமுறையின் மூலக்கல்லாகும், அங்கு எந்தவொரு குறியீடும் எழுதப்படுவதற்கு முன்பு API ஒப்பந்தம் வடிவமைக்கப்பட்டு ஒப்புக்கொள்ளப்படுகிறது. இது API வணிகத் தேவைகளையும் பயனர் தேவைகளையும் ஆரம்பத்திலிருந்தே பூர்த்தி செய்வதை உறுதி செய்கிறது.
• செயல்படுத்தப்பட்ட நிலைத்தன்மை: மீண்டும் பயன்படுத்தக்கூடிய கூறுகள் மற்றும் Spectral போன்ற லின்டிங் கருவிகளைப் பயன்படுத்துவதன் மூலம், நிறுவனங்கள் தங்கள் முழு API நிலப்பரப்பிலும் வடிவமைப்புத் தரங்களையும் நிலைத்தன்மையையும் செயல்படுத்த முடியும், இது மைக்ரோ சர்வீசஸ் கட்டமைப்பில் முக்கியமானது.
• தெளிவான மதிப்புரைகள்: இந்த விவரக்குறிப்பு, கட்டிடக் கலைஞர்கள் மற்றும் பங்குதாரர்கள் மேம்பாட்டு முதலீட்டிற்கு முன் API வடிவமைப்புகளை மதிப்பாய்வு செய்து அங்கீகரிக்க ஒரு தெளிவான, மனிதர்களால் படிக்கக்கூடிய வடிவத்தை வழங்குகிறது.

சோதனையாளர்கள் மற்றும் QA குழுக்களுக்கு: நெறிப்படுத்தப்பட்ட சரிபார்ப்பு

• தானியங்கு ஒப்பந்த சோதனை: OAS கோப்பை ஒரு ஒப்பந்தமாகப் பயன்படுத்தி, API செயலாக்கம் அதன் வடிவமைப்புடன் பொருந்துகிறதா என்பதை தானாகவே சரிபார்க்கலாம். எந்தவொரு விலகலும் மேம்பாட்டுச் சுழற்சியின் ஆரம்பத்திலேயே கண்டறியப்படலாம்.
• எளிமைப்படுத்தப்பட்ட சோதனை அமைப்பு: Postman மற்றும் Insomnia போன்ற கருவிகள் ஒரு ஓபன்ஏபிஐ கோப்பை இறக்குமதி செய்து, கோரிக்கைகளின் தொகுப்பை தானாகவே உருவாக்கலாம், இது எண்ட்பாயிண்ட்கள், அளவுருக்கள் மற்றும் உள்ளடக்கக் கட்டமைப்புகளுடன் முழுமையாக உள்ளது, இது சோதனை அமைப்பை வியத்தகு முறையில் வேகப்படுத்துகிறது.
• மாக் சர்வர் உருவாக்கம்: Prism போன்ற கருவிகள் ஒரு ஓபன்ஏபிஐ ஆவணத்திலிருந்து ஒரு டைனமிக் மாக் சேவையகத்தை உருவாக்க முடியும், இது ஃப்ரண்ட்எண்ட் குழுக்கள் மற்றும் சோதனையாளர்கள் பேக்எண்ட் உருவாக்கப்படுவதற்கு முன்பே ஒரு யதார்த்தமான API உடன் வேலை செய்ய அனுமதிக்கிறது.

இறுதிப் பயனர்கள் மற்றும் கூட்டாளர்களுக்கு: ஒரு உயர்ந்த டெவலப்பர் அனுபவம் (DX)

• ஊடாடும் ஆவணப்படுத்தல்: Swagger UI மற்றும் Redoc போன்ற கருவிகள் ஒரு ஓபன்ஏபிஐ கோப்பை அழகான, ஊடாடும் ஆவணப்படுத்தலாக மாற்றுகின்றன, அங்கு பயனர்கள் எண்ட்பாயிண்ட்களைப் பற்றிப் படிக்கலாம் மற்றும் உலாவியில் நேரடியாக அவற்றை முயற்சி செய்யலாம்.
• வேகமான ஒருங்கிணைப்பு: தெளிவான, துல்லியமான மற்றும் இயந்திரத்தால் படிக்கக்கூடிய ஆவணங்கள், மூன்றாம் தரப்பு டெவலப்பர்கள் உங்கள் API உடன் ஒருங்கிணைக்கத் தேவையான நேரத்தையும் முயற்சியையும் வியத்தகு முறையில் குறைக்கின்றன, இது தத்தெடுப்பை அதிகரிக்கிறது.

நடைமுறை வழிகாட்டி: உங்கள் முதல் ஓபன்ஏபிஐ ஆவணத்தை உருவாக்குதல்

நமது "Global Book Catalog API"-க்காக ஒரு அடிப்படை ஓபன்ஏபிஐ 3.0 விவரக்குறிப்பை உருவாக்குவதன் மூலம் கோட்பாட்டை நடைமுறைக்குக் கொண்டு வருவோம். அதன் வாசிப்புத் திறனுக்காக நாம் YAML-ஐப் பயன்படுத்துவோம்.

படி 1: அடிப்படை தகவல் மற்றும் சேவையகங்களை வரையறுத்தல்

மெட்டாடேட்டா மற்றும் புரொடக்ஷன் சர்வர் URL உடன் தொடங்குகிறோம்.

openapi: 3.0.3
info:
  title: Global Book Catalog API
  description: An API for accessing a catalog of books from around the world.
  version: 1.0.0
servers:
  - url: https://api.globalbooks.com/v1

படி 2: `components` இல் மீண்டும் பயன்படுத்தக்கூடிய தரவு மாதிரியை வரையறுத்தல்

எங்கள் எண்ட்பாயிண்ட்களை வரையறுப்பதற்கு முன், ஒரு `Book` ஆப்ஜெக்ட்டுக்கான மீண்டும் பயன்படுத்தக்கூடிய ஸ்கீமாவை உருவாக்குவோம். இது எங்கள் வடிவமைப்பை சுத்தமாகவும் சீராகவும் வைத்திருக்கிறது.

components:
  schemas:
    Book:
      type: object
      properties:
        isbn:
          type: string
          description: The International Standard Book Number.
          example: '978-0321765723'
        title:
          type: string
          description: The title of the book.
          example: 'The C++ Programming Language'
        author:
          type: string
          description: The author of the book.
          example: 'Bjarne Stroustrup'
        publicationYear:
          type: integer
          description: The year the book was published.
          example: 2013
      required:
        - isbn
        - title
        - author

படி 3: `paths` இல் எண்ட்பாயிண்ட்களை வரையறுத்தல்

இப்போது, நாம் இரண்டு எண்ட்பாயிண்ட்களை உருவாக்குவோம்: ஒன்று புத்தகங்களின் பட்டியலைப் பெறுவதற்கும், மற்றொன்று அதன் ISBN மூலம் ஒரு குறிப்பிட்ட புத்தகத்தைப் பெறுவதற்கும்.

$ref: '#/components/schemas/Book' என்பதன் பயன்பாட்டைக் கவனியுங்கள். இப்படித்தான் நாம் நமது மீண்டும் பயன்படுத்தக்கூடிய `Book` ஸ்கீமாவைக் குறிப்பிடுகிறோம்.

paths:
  /books:
    get:
      summary: List all available books
      description: Returns a list of books, optionally filtered.
      operationId: listBooks
      responses:
        '200':
          description: A successful response with an array of books.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Book'

  /books/{isbn}:
    get:
      summary: Get a book by its ISBN
      description: Returns a single book identified by its ISBN.
      operationId: getBookByIsbn
      parameters:
        - name: isbn
          in: path
          required: true
          description: The ISBN of the book to retrieve.
          schema:
            type: string
      responses:
        '200':
          description: The requested book.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
        '404':
          description: The book with the specified ISBN was not found.

படி 4: பாதுகாப்பைச் சேர்த்தல்

ஒரு ஹெடரில் அனுப்பப்பட வேண்டிய எளிய API கீ மூலம் எங்கள் API-ஐப் பாதுகாப்போம். முதலில், `components`-ல் திட்டத்தை வரையறுத்து, பின்னர் அதை உலகளவில் பயன்படுத்துகிறோம்.

# இதை 'components' பிரிவில் சேர்க்கவும்
components:
  # முந்தைய ஸ்கீமாக்கள்
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

# இதை ஆவணத்தின் ரூட் லெவலில் சேர்க்கவும்
security:
  - ApiKeyAuth: []

படி 5: சரிபார்த்தல் மற்றும் காட்சிப்படுத்தல்

உங்கள் முழுமையான YAML கோப்புடன், நீங்கள் இப்போது பல்வேறு கருவிகளைப் பயன்படுத்தலாம்:

• சரிபார்க்க: உங்கள் குறியீட்டை ஆன்லைன் ஸ்வேகர் எடிட்டரில் ஒட்டி, ஏதேனும் தொடரியல் பிழைகள் அல்லது விவரக்குறிப்பு மீறல்களைச் சரிபார்க்கவும்.
• காட்சிப்படுத்த: அழகான, ஊடாடும் ஆவணங்களை உருவாக்க ஸ்வேகர் UI அல்லது Redoc-ஐப் பயன்படுத்தவும். பெரும்பாலான கருவிகள் உங்கள் YAML/JSON கோப்பிற்கு சுட்டிக்காட்டினால் போதும், மீதமுள்ளதை அவை கவனித்துக் கொள்ளும்.

ஓபன்ஏபிஐ சுற்றுச்சூழல் அமைப்பு: கருவிகள் மற்றும் தொழில்நுட்பங்கள்

OAS-இன் சக்தி அதன் பரந்த மற்றும் முதிர்ந்த கருவிகளின் சுற்றுச்சூழல் அமைப்பால் பெருக்கப்படுகிறது. உங்கள் தேவை எதுவாக இருந்தாலும், அதற்கொரு கருவி இருக்க வாய்ப்புள்ளது:

• எடிட்டர்கள் & லின்டர்கள்: ஓபன்ஏபிஐ நீட்டிப்புகளுடன் கூடிய VS Code, Stoplight Studio, Swagger Editor, மற்றும் Spectral (லின்டிங்கிற்கு).
• ஆவண உருவாக்கிகள்: Swagger UI (மிகவும் பிரபலமானது), Redoc, மற்றும் ReadMe.
• குறியீடு உருவாக்கிகள்: OpenAPI Generator, Swagger Codegen, மற்றும் பல்வேறு மொழி-சார்ந்த கருவிகள்.
• சோதனை & மாக்கிங்: Postman, Insomnia, Prism, மற்றும் Mockoon.
• API கேட்வேஸ் & மேலாண்மை: Kong, Tyk, Apigee போன்ற பெரும்பாலான நவீன கேட்வேக்கள் மற்றும் கிளவுட் வழங்குநர் தீர்வுகள் (AWS API Gateway, Azure API Management) ரூட்டிங், பாதுகாப்பு மற்றும் விகித வரம்பை உள்ளமைக்க ஓபன்ஏபிஐ வரையறைகளை இறக்குமதி செய்ய முடியும்.

ஓபன்ஏபிஐ-யின் எதிர்காலம்: OAS 3.1 மற்றும் அதற்கு அப்பால்

ஓபன்ஏபிஐ விவரக்குறிப்பு தொடர்ந்து உருவாகி வருகிறது. சமீபத்திய முக்கிய பதிப்பான OAS 3.1, பல குறிப்பிடத்தக்க மேம்பாடுகளை அறிமுகப்படுத்தியது:

• முழுமையான JSON ஸ்கீமா இணக்கத்தன்மை: OAS 3.1 இப்போது சமீபத்திய JSON ஸ்கீமா வரைவுடன் (2020-12) 100% இணக்கமானது. இது API விவரக்குறிப்பு மற்றும் தரவு மாடலிங் உலகங்களை ஒன்றிணைத்து, மேலும் சக்திவாய்ந்த மற்றும் தரப்படுத்தப்பட்ட ஸ்கீமாக்களை அனுமதிக்கிறது.
• வெப்ஹூக்குகள்: இது ஒத்திசைவற்ற, நிகழ்வு-சார்ந்த ஏபிஐ-களை விவரிக்க ஒரு தரப்படுத்தப்பட்ட வழியை வழங்குகிறது, அங்கு சேவையகம் கிளையண்டுடன் தொடர்பைத் தொடங்குகிறது (எ.கா., ஒரு ஆர்டர் புதுப்பிக்கப்படும்போது அறிவிப்பு அனுப்புதல்).
• ஓவர்லேஸ் மற்றும் தரநிலைகள்: ஓவர்லேஸ் போன்ற கருத்துக்கள் மூலம் விவரக்குறிப்புகளை மேலும் மாடுலர் மற்றும் மீண்டும் பயன்படுத்தக்கூடியதாக மாற்றுவதில் தற்போதைய பணிகள் கவனம் செலுத்துகின்றன, இது ஒரு அடிப்படை விவரக்குறிப்பை நேரடியாக மாற்றாமல் நீட்டிக்க உங்களை அனுமதிக்கிறது.

இந்த முன்னேற்றங்கள், ஒரு நவீன, API-முதல், மற்றும் நிகழ்வு-சார்ந்த கட்டமைப்பில் ஓபன்ஏபிஐ-யின் மைய நிலையை உறுதிப்படுத்துகின்றன.

முடிவுரை: நவீன மேம்பாட்டின் ஒரு மூலக்கல்

ஓபன்ஏபிஐ விவரக்குறிப்பு நாம் ஏபிஐ-களைப் பற்றி சிந்திக்கும் விதத்தை மாற்றியுள்ளது. இது ஏபிஐ ஆவணப்படுத்தலை ஒரு அஞ்சப்படும், பெரும்பாலும் புறக்கணிக்கப்பட்ட பின் சிந்தனையிலிருந்து, முழு மேம்பாட்டு வாழ்க்கைச் சுழற்சியையும் இயக்கும் ஒரு மூலோபாய, வாழும் ஆவணமாக உயர்த்தியுள்ளது. ஒரு இயந்திரத்தால் படிக்கக்கூடிய ஒப்பந்தமாகச் செயல்படுவதன் மூலம், OAS ஒத்துழைப்பை வளர்க்கிறது, சக்திவாய்ந்த ஆட்டோமேஷனை செயல்படுத்துகிறது, நிலைத்தன்மையைச் செயல்படுத்துகிறது, மேலும் இறுதியில் சிறந்த, நம்பகமான மற்றும் எளிதாகப் பயன்படுத்தக்கூடிய ஏபிஐ-களின் உருவாக்கத்திற்கு வழிவகுக்கிறது.

நீங்கள் ஒரு டெவலப்பர், கட்டிடக் கலைஞர், தயாரிப்பு மேலாளர் அல்லது சோதனையாளராக இருந்தாலும், ஓபன்ஏபிஐ விவரக்குறிப்பைத் தழுவுவது நவீன மென்பொருள் மேம்பாட்டில் தேர்ச்சி பெறுவதற்கான ஒரு முக்கியமான படியாகும். நீங்கள் ஏற்கனவே அதைப் பயன்படுத்தவில்லை என்றால், உங்கள் அடுத்த திட்டத்துடன் தொடங்க பரிசீலிக்கவும். முதலில் ஒப்பந்தத்தை வரையறுத்து, அதை உங்கள் குழுவுடன் பகிர்ந்து, உங்கள் டிஜிட்டல் ஒத்துழைப்புகளில் ஒரு புதிய அளவிலான செயல்திறனையும் தெளிவையும் திறக்கவும்.