प्रौद्योगिकी साझेदारी

Apispec, OpenAPI (Swagger) विनिर्देशान् जनयितुं Python पुस्तकालयः

2024-07-12

한어Русский языкEnglishFrançaisIndonesianSanskrit日本語DeutschPortuguêsΕλληνικάespañolItalianoSuomalainenLatina

सामग्रीसूची

01एपिआइस्पेक् किम् ?

एपिस्पेक् किमर्थं चिनोति ?

संस्थापनं विन्यासश्च

02Apispec इत्यस्य मूलभूतः उपयोगः

सरलं एपिआइ दस्तावेजीकरणं जनयन्तु

1. Apispec उदाहरणं रचयन्तु

2. एपिआइ मार्गाः दृश्यानि च परिभाषयन्तु

3. Apispec मध्ये मार्गं योजयन्तु

Flask तथा APIspec एकीकृत करें

1. Flask तथा Flask-Apispec संस्थापयन्तु

2. Flask अनुप्रयोगं रचयन्तु

Django तथा APIspec एकीकृत्य

1. Django तथा Django-Rest-Framework संस्थापयन्तु

2. Django परियोजनानि अनुप्रयोगाः च रचयन्तु

3. Django परियोजना विन्यस्तं कुर्वन्तु

4. Django दृश्यानि परिभाषयन्तु

5. URL विन्यस्तं कुर्वन्तु

6. OpenAPI विनिर्देशं जनयन्तु

03Apispec इत्यस्य उन्नतविशेषताः

1. कस्टम जनरेटर

2. बहुविधरूपरेखानां समर्थनं कुर्वन्तु

3. स्वयमेव अन्तरफलकदस्तावेजान् जनयन्तु

4. तृतीयपक्षीयसाधनैः सह एकीकरणं कुर्वन्तु

०४व्यावहारिकप्रकरणाः

1. परियोजना परिचय

2. परियोजना संरचना

3. आश्रयाणि संस्थापयन्तु

4. आदर्शं परिभाषयतु

5. दृश्यानि क्रमाङ्कनं च परिभाषयन्तु

6. मुख्यानुप्रयोगं परिभाषयन्तु

7. एप् चालयित्वा दस्तावेजीकरणं पश्यन्तु

उत्पन्नं एपिआइ-दस्तावेजं द्रष्टुं http://localhost:5000/swagger/ इति गच्छन्तु ।

05उत्तम अभ्यास

०६ सारांशः


01एपिआइस्पेक् इति किम् ?

एपिआइस्पेस् इत्यस्य परिचयः

Apispec OpenAPI (Swagger) विनिर्देशान् जनयितुं Python पुस्तकालयः अस्ति । एतत् विकासकान् स्वयमेव एपिआइ-दस्तावेजान् जनयितुं परिपालयितुं च सहायं कर्तुं शक्नोति तथा च सहजं विस्तृतं च अन्तरफलकं विवरणं प्रदातुं शक्नोति । Apispec इत्यस्य माध्यमेन वयं Python फंक्शन् अथवा क्लास् इत्यस्य documentation स्ट्रिंग् इत्येतत् OpenAPI विनिर्देशस्य अनुरूपं दस्तावेजे सहजतया परिवर्तयितुं शक्नुमः, येन दस्तावेजीकरणं मैन्युअल् रूपेण लेखनस्य कष्टं न्यूनीकरोति

एपिस्पेक् किमर्थं चिनोति ?

  • सरलं सुलभं च: Apispec सरलं सुलभं च API प्रदाति येन भवान् शीघ्रं आरभुं शक्नोति।

  • लचीला तथा शक्तिशाली: बहुविधरूपरेखां (यथा Flask, Django) विस्तारं च समर्थयति, यत् आवश्यकतानुसारं दस्तावेजजननं अनुकूलितुं शक्नोति ।

  • स्वचालनम्: स्वयमेव दस्तावेजान् जनयित्वा अद्यतनं कृत्वा हस्तचलितसञ्चालनस्य अनुरक्षणस्य च व्ययस्य न्यूनीकरणं कुर्वन्तु।

संस्थापनं विन्यासश्च

Apispec इत्यस्य उपयोगं आरभ्यतुं पूर्वं प्रथमं तत् संस्थापयितुं आवश्यकम् । भवान् pip इत्यस्य उपयोगेन संस्थापयितुं शक्नोति:

pip install apispec

Github परियोजना पता:

https://github.com/marshmallow-code/apispec

02APIspec इत्यस्य मूलभूतः उपयोगः

कतिपयानां सरलानाम् उदाहरणानां माध्यमेन Apispec इत्यस्य मूलभूतं उपयोगं पश्यामः ।

सरलं एपिआइ दस्तावेजीकरणं जनयन्तु

1. Apispec उदाहरणं रचयन्तु

  1. from apispec import APISpec
  2.  
  3. spec = APISpec(
  4.     title="My API",
  5.     version="1.0.0",
  6.     openapi_version="3.0.0",
  7.     info=dict(description="This is a sample API"),
  8. )

2. एपिआइ मार्गाः दृश्यानि च परिभाषयन्तु

  1. def get_user(user_id):
  2.     """
  3.     ---
  4.     get:
  5.       description: Get a user by ID
  6.       parameters:
  7.         - name: user_id
  8.           in: path
  9.           required: true
  10.           schema:
  11.             type: integer
  12.       responses:
  13.         200:
  14.           description: A user object
  15.           content:
  16.             application/json:
  17.               schema:
  18.                 type: object
  19.                 properties:
  20.                   id:
  21.                     type: integer
  22.                   name:
  23.                     type: string
  24.     """
  25.     return {"id": user_id, "name": "John Doe"}

3. Apispec मध्ये मार्गं योजयन्तु

  1. spec.path(
  2.     path="/users/{user_id}",
  3.     operations=dict(
  4.         get=dict(
  5.             description="Get a user by ID",
  6.             parameters=[
  7.                 {
  8.                     "name": "user_id",
  9.                     "in": "path",
  10.                     "required": True,
  11.                     "schema": {"type": "integer"},
  12.                 }
  13.             ],
  14.             responses={
  15.                 "200": {
  16.                     "description": "A user object",
  17.                     "content": {
  18.                         "application/json": {
  19.                             "schema": {
  20.                                 "type": "object",
  21.                                 "properties": {
  22.                                     "id": {"type": "integer"},
  23.                                     "name": {"type": "string"},
  24.                                 },
  25.                             }
  26.                         }
  27.                     },
  28.                 }
  29.             },
  30.         )
  31.     ),
  32. )

Flask तथा APIspec एकीकृत करें

1. Flask तथा Flask-Apispec संस्थापयन्तु

pip install Flask Flask-Apispec

2. Flask अनुप्रयोगं रचयन्तु

  1. from flask import Flask, jsonify
  2. from flask_apispec import FlaskApiSpec, doc, marshal_with
  3. from flask_apispec.views import MethodResource
  4. from marshmallow import Schema, fields
  5.  
  6. app = Flask(__name__)
  7.  
  8. class UserSchema(Schema):
  9.     id = fields.Int()
  10.     name = fields.Str()
  11.  
  12. class UserResource(MethodResource):
  13.     @doc(description='Get a user by ID', tags=['User'])
  14.     @marshal_with(UserSchema)
  15.     def get(self, user_id):
  16.         return {"id": user_id, "name": "John Doe"}
  17.  
  18. app.add_url_rule('/users/<int:user_id>', view_func=UserResource.as_view('user_resource'))
  19. docs = FlaskApiSpec(app)
  20. docs.register(UserResource)
  21.  
  22. @app.route('/swagger/')
  23. def swagger_ui():
  24.     return jsonify(docs.spec.to_dict())
  25.  
  26. if __name__ == '__main__':
  27.     app.run()

Django तथा APIspec एकीकृत्य

1. Django तथा Django-Rest-Framework संस्थापयन्तु

pip install django djangorestframework

2. Django परियोजनानि अनुप्रयोगाः च रचयन्तु

  1. django-admin startproject myproject
  2. cd myproject
  3. django-admin startapp myapp

3. Django परियोजना विन्यस्तं कुर्वन्तु

settings.py मध्ये rest_framework तथा apispec योजयन्तु:

  1. INSTALLED_APPS = [
  2.     ...
  3.     'rest_framework',
  4.     'myapp',
  5.     'apispec',
  6. ]

4. Django दृश्यानि परिभाषयन्तु

myapp/views.py इत्यत्र:

  1. from rest_framework.views import APIView
  2. from rest_framework.response import Response
  3. from rest_framework.schemas import AutoSchema
  4.  
  5. class UserView(APIView):
  6.     schema = AutoSchema(
  7.         manual_fields=[
  8.             coreapi.Field('user_id', required=True, location='path', schema={'type': 'integer'})
  9.         ]
  10.     )
  11.  
  12.     def get(self, request, user_id):
  13.         """
  14.         Get a user by ID.
  15.         ---
  16.         responses:
  17.           200:
  18.             description: A user object
  19.             content:
  20.               application/json:
  21.                 schema:
  22.                   type: object
  23.                   properties:
  24.                     id:
  25.                       type: integer
  26.                     name:
  27.                       type: string
  28.         """
  29.         return Response({"id": user_id, "name": "John Doe"})

5. URL विन्यस्तं कुर्वन्तु

myapp/urls.py इत्यत्र:

  1. from django.urls import path
  2. from .views import UserView
  3.  
  4. urlpatterns = [
  5.     path('users/<int:user_id>/', UserView.as_view(), name='user-view'),
  6. ]

6. OpenAPI विनिर्देशं जनयन्तु

manage.py इत्यत्र :

  1. from apispec import APISpec
  2. from rest_framework.schemas import get_schema_view
  3.  
  4. spec = APISpec(
  5.     title="My API",
  6.     version="1.0.0",
  7.     openapi_version="3.0.0",
  8. )
  9.  
  10. schema_view = get_schema_view(title="My API")
  11. schema = schema_view.get_schema(request=None, public=True)
  12. spec.components.schema('User', schema)
  13. spec.path(path='/users/{user_id}/', operations=schema['paths']['/users/{user_id}/'])
  14.  
  15. print(spec.to_yaml())

03APIspec इत्यस्य उन्नतविशेषताः

1. कस्टम जनरेटर

APIspec एकं लचीलं विस्तारतन्त्रं प्रदाति यत् भवन्तं जनरेटर् अनुकूलितुं शक्नोति । Apispec द्वारा प्रदत्तं आधारवर्गं उत्तराधिकारं प्राप्य विस्तारं कृत्वा भवान् स्वस्य जननतर्कं कार्यान्वितुं शक्नोति ।

  1. from apispec import BasePlugin
  2.  
  3. class MyPlugin(BasePlugin):
  4.     def path_helper(self, operations, *, resource, **kwargs):
  5.         operations.update({
  6.             'get': {
  7.                 'description': 'Get a user by ID',
  8.                 'parameters': [
  9.                     {'name': 'user_id', 'in': 'path', 'required': True, 'schema': {'type': 'integer'}}
  10.                 ],
  11.                 'responses': {
  12.                     '200': {
  13.                         'description': 'A user object',
  14.                         'content': {
  15.                             'application/json': {
  16.                                 'schema': {
  17.                                     'type': 'object',
  18.                                     'properties': {
  19.                                         'id': {'type': 'integer'},
  20.                                         'name': {'type': 'string'}
  21.                                     }
  22.                                 }
  23.                             }
  24.                         }
  25.                     }
  26.                 }
  27.             }
  28.         })
  29.  
  30. spec = APISpec(
  31.     title="My API",
  32.     version="1.0.0",
  33.     openapi_version="3.0.0",
  34.     plugins=[MyPlugin()],
  35. )

2. बहुविधरूपरेखानां समर्थनं कुर्वन्तु

एपिस्पेक् विविधं लोकप्रियं पायथन्-रूपरेखां समर्थयति, यथा Flask, Django, Falcon इत्यादीनि । शीघ्रं एपिआइ दस्तावेजान् जनयितुं भवान् स्वस्य आवश्यकतानुसारं समुचितं ढाञ्चं प्लग-इन् च चिन्वितुं शक्नोति ।

3. स्वयमेव अन्तरफलकदस्तावेजान् जनयन्तु

एपिस्पेक् स्वयमेव कस्यचित् फंक्शन् अथवा क्लास् इत्यस्य दस्तावेजीकरणस्ट्रिंग् इत्यस्य आधारेण अन्तरफलकदस्तावेजान् जनयितुं शक्नोति, येन दस्तावेजान् मैन्युअल् रूपेण लेखनस्य कार्यभारः न्यूनीकरोति ।

  1. def get_user(user_id):
  2.     """
  3.     ---
  4.     get:
  5.       description: Get a user by ID
  6.       parameters:
  7.         - name: user_id
  8.           in: path
  9.           required: true
  10.           schema:
  11.             type: integer
  12.       responses:
  13.         200:
  14.           description: A user object
  15.           content:
  16.             application/json:
  17.               schema:
  18.                 type: object
  19.                 properties:
  20.                   id:
  21.                     type: integer
  22.                   name:
  23.                     type: string
  24.     """
  25.     return {"id": user_id, "name": "John Doe"}

4. तृतीयपक्षीयसाधनैः सह एकीकरणं कुर्वन्तु

Apispec इत्येतत् अनेकैः तृतीयपक्षीयसाधनैः सह एकीकृत्य, यथा Swagger UI, ReDoc इत्यादिभिः सह, सहजज्ञानयुक्तं अन्तरफलकदस्तावेजप्रदर्शनं परीक्षणकार्यं च प्रदातुं शक्यते ।

  1. from flask import Flask, jsonify
  2. from flask_apispec import FlaskApiSpec
  3.  
  4. app = Flask(__name__)
  5.  
  6. @app.route('/users/<int:user_id>', methods=['GET'])
  7. def get_user(user_id):
  8.     """
  9.     ---
  10.     get:
  11.       description: Get a user by ID
  12.       parameters:
  13.         - name: user_id
  14.           in: path
  15.           required: true
  16.           schema:
  17.             type: integer
  18.       responses:
  19.         200:
  20.           description: A user object
  21.           content:
  22.             application/json:
  23.               schema:
  24.                 type: object
  25.                 properties:
  26.                   id:
  27.                     type: integer
  28.                   name:
  29.                     type: string
  30.     """
  31.     return jsonify({"id": user_id, "name": "John Doe"})
  32.  
  33. docs = FlaskApiSpec(app)
  34. docs.register(get_user)
  35.  
  36. if __name__ == '__main__':
  37.     app.run()

04व्यावहारिकप्रकरणाः

एकं सम्पूर्णं एपिआइ दस्तावेजीकरणप्रणालीं निर्मायताम्

1. परियोजना परिचय

मानातु अस्माकं सरलं उपयोक्तृप्रबन्धनप्रणाली अस्ति तस्य एपिआइ दस्तावेजीकरणस्य आवश्यकता अस्ति । अस्माकं एपिआइ मध्ये उपयोक्तृसंयोजनं, विलोपनं, परिवर्तनं, प्रश्नक्रियाः, तथैव केचन मूलभूतपरिचयप्रमाणीकरणकार्यं च समाविष्टम् अस्ति ।

2. परियोजना संरचना

  1. user_management/
  2. ├── app.py
  3. ├── models.py
  4. ├── views.py
  5. ├── serializers.py
  6. └── requirements.txt

3. आश्रयाणि संस्थापयन्तु

requirements.txt इत्यत्र आश्रयाणि योजयन्तु:

  1. Flask
  2. Flask-RESTful
  3. Flask-SQLAlchemy
  4. Flask-Migrate
  5. apispec
  6. flask-apispec

निर्भरतां संस्थापयितुं निम्नलिखितम् आदेशं चालयन्तु ।

pip install -r requirements.txt

4. आदर्शं परिभाषयतु

models.py इत्यस्मिन् उपयोक्तृप्रतिरूपं परिभाषयन्तु:

  1. from flask_sqlalchemy import SQLAlchemy
  2.  
  3. db = SQLAlchemy()
  4.  
  5. class User(db.Model):
  6.     id = db.Column(db.Integer, primary_key=True)
  7.     name = db.Column(db.String(80), nullable=False)
  8.     email = db.Column(db.String(120), unique=True, nullable=False)

5. दृश्यानि क्रमाङ्कनं च परिभाषयन्तु

serializers.py इत्यस्मिन् उपयोक्तृक्रमाङ्ककाः परिभाषयन्तु:

  1. from marshmallow import Schema, fields
  2.  
  3. class UserSchema(Schema):
  4.     id = fields.Int(dump_only=True)
  5.     name = fields.Str(required=True)
  6.     email = fields.Email(required=True)
  7.

views.py इत्यत्र दृश्यानि परिभाषयन्तु:

  1. from flask import request
  2. from flask_restful import Resource
  3. from models import User, db
  4. from serializers import UserSchema
  5.  
  6. class UserResource(Resource):
  7.     def get(self, user_id):
  8.         user = User.query.get_or_404(user_id)
  9.         schema = UserSchema()
  10.         return schema.dump(user)
  11.  
  12.     def post(self):
  13.         schema = UserSchema()
  14.         user = schema.load(request.json)
  15.         db.session.add(user)
  16.         db.session.commit()
  17.         return schema.dump(user), 201
  18.  
  19.     def put(self, user_id):
  20.         user = User.query.get_or_404(user_id)
  21.         schema = UserSchema(partial=True)
  22.         updated_user = schema.load(request.json, instance=user)
  23.         db.session.commit()
  24.         return schema.dump(updated_user)
  25.  
  26.     def delete(self, user_id):
  27.         user = User.query.get_or_404(user_id)
  28.         db.session.delete(user)
  29.         db.session.commit()
  30.         return '', 204

6. मुख्यानुप्रयोगं परिभाषयन्तु

app.py इत्यत्र : १.

  1. from flask import Flask
  2. from flask_restful import Api
  3. from flask_migrate import Migrate
  4. from models import db
  5. from views import UserResource
  6. from flask_apispec import FlaskApiSpec
  7. from flask_apispec.extension import FlaskApiSpec
  8.  
  9. app = Flask(__name__)
  10. app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///users.db'
  11. db.init_app(app)
  12. migrate = Migrate(app, db)
  13. api = Api(app)
  14.  
  15. api.add_resource(UserResource, '/users/<int:user_id>')
  16.  
  17. docs = FlaskApiSpec(app)
  18. docs.register(UserResource)
  19.  
  20. if __name__ == '__main__':
  21.     app.run()

7. एप् चालयित्वा दस्तावेजीकरणं पश्यन्तु

निम्नलिखित आदेशं चालयित्वा अनुप्रयोगं आरभत:

python app.py

उत्पन्नं एपिआइ-दस्तावेजं द्रष्टुं http://localhost:5000/swagger/ इति गच्छन्तु ।

05उत्तम अभ्यास

1. दस्तावेजीकरणं कोडं च समन्वयेन स्थापयन्तु

दस्तावेजीकरणस्य वास्तविक-एपिआइ-इत्यस्य च मध्ये असङ्गतिं परिहरितुं दस्तावेजीकरणं सदैव कोडेन सह समन्वयं भवति इति सुनिश्चितं कुर्वन्तु । स्वयमेव दस्तावेजीकरणं जनयितुं परिनियोजितुं च भवान् CI/CD उपकरणानां उपयोगं कर्तुं शक्नोति ।

2. एनोटेशन्स् तथा अलङ्कारस्य उपयोगं कुर्वन्तु

टिप्पणीनां, अलङ्कारस्य च उपयोगेन दस्तावेजीकरणं अधिकं संक्षिप्तं पठनीयं च कर्तुं शक्यते । उदाहरणार्थं, दृश्यकार्यं प्रति दस्तावेजीकरणसूचनाः योजयितुं Flask-Apispec इत्यस्य @doc decorator इत्यस्य उपयोगं कुर्वन्तु ।

3. वैश्विकमापदण्डान् प्रतिक्रियाश्च परिभाषयन्तु

सामान्यतया प्रयुक्तानां मापदण्डानां प्रतिक्रियाणां च कृते, पुनरावृत्तिसङ्केतस्य न्यूनीकरणाय Apispec इत्यस्मिन् वैश्विकमापदण्डाः प्रतिक्रियासारूप्याणि च परिभाषितुं शक्यन्ते ।

  1. spec.components.parameter("user_id", "path", schema={"type": "integer"}, required=True)
  2. spec.components.response("User", {
  3.     "description": "A user object",
  4.     "content": {
  5.         "application/json": {
  6.             "schema": {
  7.                 "type": "object",
  8.                 "properties": {
  9.                     "id": {"type": "integer"},
  10.                     "name": {"type": "string"}
  11.                 }
  12.             }
  13.         }
  14.     }
  15. })

4. नियमितरूपेण दस्तावेजानां समीक्षां कृत्वा अद्यतनं कुर्वन्तु

सटीकताम् पूर्णतां च सुनिश्चित्य दस्तावेजानां नियमितरूपेण समीक्षां कृत्वा अद्यतनं कुर्वन्तु। एतत् दस्तावेजसमीक्षाचक्रं स्थापयित्वा अथवा दस्तावेजसमीक्षाप्रक्रियायाः परिचयं कृत्वा प्राप्तुं शक्यते ।

अधिककार्यं विस्तृतप्रयोगाय च आधिकारिकदस्तावेजं पश्यन्तु:

https://apispec.readthedocs.io/en/latest

06संक्षेपः

अस्य लेखस्य माध्यमेन मम विश्वासः अस्ति यत् भवतः एपिस्पेक् विषये मूलभूतं अवगमनं निपुणता च अस्ति। मूलभूतप्रयोगात् उन्नतकार्यपर्यन्तं, व्यावहारिकप्रकरणानाम् उत्तमप्रथानां च यावत्, वयं एपिआइ दस्तावेजान् जनयितुं परिपालयितुं च Apispec इत्यस्य उपयोगः कथं करणीयः इति व्यापकरूपेण परिचययामः।

आशासे यत् भवान् एतत् ज्ञानं वास्तविकप्रकल्पेषु प्रयोक्तुं शक्नोति तथा च स्वस्य एपिआइ मध्ये प्रकाशस्य स्पर्शं योजयितुं शक्नोति।

व्यक्तिगत प्रोफाइल

सः ३० वर्षाणाम् अधिकं कालात् प्रौद्योगिक्याः शोधकार्यं कर्तुं समर्पितः अस्ति, तथा च जावा, लिनक्स, जावास्क्रिप्ट्, php, css इत्यादिषु विविधभाषासु प्रवीणः अस्ति, मुक्तस्रोतक्षेत्रे सः बहु योगदानं कृतवान् अस्ति developer documentation station भविष्ये सन्दर्भार्थं प्रौद्योगिकीविकासे केचन विषयाः साझां कर्तुं सर्वे तत् पश्यन्तु

मम सम्पर्कसूचना

मेल