PyCon Korea 2019 REST API Document Generation

PyCon Korea 2019
AITRICS
REST API

5

Python backend app

Flask 2 Django

●REST API

●OpenAPI Specification

●Python Web Applications & OpenAPI Specification

●Django API

●Flask API

REST API ?
HTTP
METHODS
https://api.example.com/speakers https://api.example.com/speakers/1
GET 1
POST -
PUT
request body
request body field null
1 request body
request body field null
PATCH
request body
request body field
1 request body
request body field
DELETE 1
OpenAPI Specification Python Web Apps & OAS Django FlaskREST API
Representational State Transfer

( API )
REST API

●API ,

●Host, port

●

●URI

●URI HTTP method

● request header, body

● response status code, body
REST API

REST API

.. 

● ..

●

●
REST API

RESTful API

JSON, YAML

API , /  
Swagger OpenAPI Initiative
OpenAPI Specification
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md
REST API Python Web Apps & OAS Django FlaskOpenAPI Specification

API

toolset

●Swagger Codegen

●Swagger Editor

●Swagger UI

Swagger UI
●OpenAPI JSON/YAML  
API
Swagger?
https://petstore.swagger.io/

title: Sample PyCON speaker API

description: This is a sample server for a PyCON speaker management.

termsOfService: http://example.com/terms/

contact:

name: API Support

url: http://www.example.com/support

email: support@example.com

license:

name: MIT

version: 1.0.1
OpenAPI Specification YAML

servers:

- url: https://pycon-speaker.com:{port}/{basePath}

description: The production API server

variables:

port:

enum:

- '443'

- '8443'

default: '8443'

description: 8443 is for demo.

basePath:

default: v2

paths:

/speakers:

get:

description: Returns all speakers from the system that the user has access to

responses:

'200':

description: A list of speakers.

content:

application/json:

schema:

type: array

items:

$ref: '#/components/schemas/Speaker'

components:

schemas:

Speaker:

required:

- id

- email

properties:

id:

type: integer

format: int64

email:

type: string

name:

type: string


OpenAPI Specification 
JSON / YAML
APISwagger UI
paths:

/speakers:

get:

description: Returns all speakers from the system
that the user has access to

responses:

'200':


content:

application/json:

schema:

type: array

items:


Python Web Application &  
OpenAPI Specification

Generating OpenAPI YAML
Web Application Server
●Server information

○Base URL, port, ...

●Routing information

○ path

●Request params

●Response schema
REST API OpenAPI Specification Django FlaskPython Web Apps & OAS

servers:

- url: https://pycon-speaker.com:{port}/{basePath}

description: The production API server

variables:

port:

enum:

- '443'

- '8443'

default: '8443'

description: 8443 is for demo.

basePath:

default: v2

○Routing information

■ Request params

■ Response schema

paths:

/speakers:

get:

description: Returns all speakers

responses:

'200':


content:

application/json:

schema:

type: array

items:


○Routing information

■ Request params

■ Response schema

Django & OAS
Django Server
●Server information →

○Routing information → urls.urlpatterns

■ Request params → View, Model

■ Response schema → View, Model

Django & OAS
Server Information
● ,

Routing Information
●urlpatterns
# urls.py

openapi_schema_view = get_schema_view(

openapi.Info(

title='Demo API',

default_version='v1',

),

url='https://demo.example.com:3000',

public=True,

)

urlpatterns = [

path('admin/', admin.site.urls),

path('docs/', openapi_schema_view.with_ui(...),

path('', include(router.urls)),

]

Django & OAS
Request Params, Response Schema
●Function Based View
○ view request, response

■ docstring ? 
→ API
def speakers_list(request):

"""

response

- type: list

- content

- name: , string

- email: , string

- organization: , object

- name: , string

"""

...

return speakers

django/views/generics/edit.py
Django & OAS
●Class Based View
○django/views/generics

○cls.model model  
→ response schema

○cls.get_form_class() form  
→ request parameters
CreateView
ModelFormMixin
get_form_class()
SingleObjectMixin
model

Flask & OAS
Flask Server
●Server information →

○Routing information → Flask.view_functions

■ Request params → View?, Model?

■ Response schema → View?, Model?

Flask & OAS
Routing Information
●Flask.view_functions
# flask/app.py: Flask

def route(self, rule, **options):

def decorator(f):

endpoint = options.pop('endpoint', None)

self.add_url_rule(rule, endpoint, f, **options)

return f

return decorator

def add_url_rule(self, rule, endpoint, view_func, ...):

…

self.view_functions[endpoint] = view_func

…

Flask & OAS
●Function View (Django )
○ view request, response

■ docstring ? → API

●Pluggable View(Class Based View)
○Function View Extension

○

●Routing information
○ framework routing

●Request params
○(Django) View class form

●Response schema
○(Django) View class model

●APIView (Django view wrapping)

●ModelViewSet (generic views)

○Serializer

○Filterset

○Permission

●OpenAPI schema ( )
Django REST Framework
REST API OpenAPI Specification Python Web Apps & OAS FlaskDjango



○Serializer
○Filterset

○Permission

>>> speaker

<Speaker: Speaker object (1)>

>>> serializer = SpeakerSerializer(speaker)

>>> serializer.data

{'email': 'test@pycon.kr',

'name': 'test',

'created': '2019-08-18T12:15:10.375877'}



○Serializer
○Filterset

○Permission

>>> data = {'email': 'another@pycon.kr',

'name': 'another test',

'created': '2019-08-18T12:16:10.375877'}

>>> serializer = SpeakerSerializer(data=data)

>>> serializer.is_valid()

True

>>> serializer.validated_data

{'email': 'another@pycon.kr',

'name': 'another test',

'created': datetime.datetime(2019, 08, 18, 12, 16, 10,
375877)}



○Serializer
○Filterset

○Permission

>>> serializer.save()

<Speaker: Speaker object (2)>



○Serializer
○Filterset

○Permission


API

●Django REST Swagger

○ https://github.com/marcgibbons/django-rest-swagger 
●DRF Yet another Swagger generator

○ https://github.com/axnsan12/drf-yasg

○ swagger/redoc UI
https://www.django-rest-framework.org/topics/documenting-your-api/


API

●Django REST Swagger

○ https://github.com/marcgibbons/django-rest-swagger

○ 2019-06-04 Deprecated… 
●DRF Yet another Swagger generator

○ https://github.com/axnsan12/drf-yasg

○ swagger/redoc UI

○
https://www.django-rest-framework.org/topics/documenting-your-api/


●View serializer request / response schema

● override decorator

●OpenAPI Spec 2.0 schema

○DRF OpenAPI schema
DRF-YASG

DRF native vs DRF-YASG
# Django REST Framework (X)

responses:

'200':

content:

application/json:

schema:

properties:

id:

type: integer

readOnly: true

date:

type: string

format: date

packages:

type: array

items:

type: string
# DRF-YASG (O)

responses:

'200':

schema:

type: object

properties:

count:

type: integer

next:

type: string

format: uri

previous:

type: string

format: uri

results:

type: array

items:

$ref: '#/definitions/Record'

DRF-YASG
urlpatterns

(url → view class mappings)
/speakers → SpeakerViewSet
serializer class = SpeakerSerializer
/organizations → OrganizationViewSet
serializer class = OrganizationSerializer

DRF-YASG
urlpatterns
SpeakerViewSet
serializer class
Speaker

(id, name, email,
organization_id)
SpeakerSerializer
model = Speaker

id: int

name: str

email: str

organization_id: int, read-only

organization:

OrganizationSerializer, write-only

DRF-YASG
urlpatterns
SpeakerViewSet
serializer class
SpeakerSerializer
model = Speaker

id: int

name: str

email: str

organization_id: int, read-only

organization:

OrganizationSerializer, write-only
OrganizationSerializer
model = Organization

id: int

name: str

DRF-YASG
# drf_yasg/views.py

class SchemaView(APIView):

...

def get(self, request, version='', format=None):

...

schema = generator.get_schema(request, self.public)

...

return Response(schema)

DRF-YASG
# drf_yasg/generators.py

class OpenAPISchemaGenerator:

def get_schema(self, request=None, public=False):

...

paths, prefix = self.get_paths(endpoints, ...)

...

return openapi.Swagger(

paths=paths,

...

)
def get_paths(self, endpoints, ...):

...

for url, (..., methods) in sorted(endpoints.items()):

...

for method, view in methods:

...

operation = self.get_operation(url, method, ...)

...

...

def get_operation(self, url, method, ...):

...

operation = view_inspector.get_operation(...)

...
urls.urlpatterns

DRF-YASG



...


...


paths=paths,

...

)

...

for path, (..., methods) in sorted(endpoints.items()):

...


...

operation = self.get_operation(path, method, ...)

...

...

def get_operation(self, path, method, ...):

...


...
paths:

/speakers:

get:


responses:

'200':


content:

application/json:

schema:

type: array

items:

urls.urlpatterns

DRF-YASG



...


...


paths=paths,

...

)

...

for url, (..., methods) in sorted(endpoints.items()):

...


...

operation = self.get_operation(url, method, ...)

...

...

def get_operation(self, url, method, ...):

...


...

DRF-YASG



...


...


paths=paths,

...

)

...


...


...


...

...


...


...
paths:

/speakers:

get:


responses:

'200':


content:

application/json:

schema:

type: array

items:


DRF-YASG



...


...


paths=paths,

...

)

...


...


...


...

...


...


...

DRF-YASG
# drf_yasg/inspectors/view.py

class SwaggerAutoSchema(ViewInspector):

def get_operation(self, operation_keys=None):

...

parameters = body + query

parameters = filter_none(parameters)

parameters = self.add_manual_parameters(parameters)

...

responses = self.get_responses()

return openapi.Operation(

parameters=parameters,

responses=responses,

...

)


DRF-YASG
# drf_yasg/inspectors/view.py

class SwaggerAutoSchema(ViewInspector):

def get_operation(self, operation_keys=None):

...

parameters = body + query

parameters = filter_none(parameters)

parameters = self.add_manual_parameters(parameters)

...

responses = self.get_responses()

return openapi.Operation(

parameters=parameters,

responses=responses,

...

)

1. self.view serializer

2. field inspector field

○ Nested serializer

○ SerializerMethodField

○ Paginated response

3. openapi Response

DRF-YASG
●urlpatterns endpoints(url → view mapping)  
●endpoints iterate url, method request response  
●request response field inspector  
Nested serializer  
● request response OpenAPI schema

DRF-YASG
# main/urls.py

...

openapi_schema_view = get_schema_view(

openapi.Info(

title='Demo API',

default_version='v1',

),

public=True,

)

urlpatterns = [

path('admin/', admin.site.urls),

path('docs/', openapi_schema_view.with_ui('redoc')),

path('', include(router.urls)),

]

DRF-YASG
# main/models.py

class Speaker(models.Model):

id = AutoField(primary_key=True)

email = EmailField()

name = CharField(max_length=10, blank=True)

organization = ForeignKey(

Organization,

null=True,

on_delete=models.SET_NULL,

related_name='speakers'

)

# main/views.py

class SpeakerViewSet(ModelViewSet):

queryset = Speaker.objects.all()

serializer_class = SpeakerSerializer

DRF-YASG
# main/serializers.py

class OrganizationSerializer(ModelSerializer):

...

class SpeakerSerializer(ModelSerializer):

organization = OrganizationSerializer(read_only=True,

help_text='Read-only ')

organization_id = PrimaryKeyRelatedField(source='organization',

queryset=Organization.objects.all(),

write_only=True,

help_text='Write-only ')

class Meta:

model = Speaker

fields = '__all__'

write_only_fields = ('organization_id',)

read_only_fields = ('organization',)

DRF-YASG
# main/serializers.py

class OrganizationSerializer(ModelSerializer):

...

class SpeakerSerializer(ModelSerializer):

organization = OrganizationSerializer(read_only=True,

help_text='Read-only ')

organization_id = PrimaryKeyRelatedField(source='organization',

queryset=Organization.objects.all(),

write_only=True,

help_text='Write-only ')

class Meta:

model = Speaker

fields = '__all__'

write_only_fields = ('organization_id',)

read_only_fields = ('organization',)
$ curl -X POST localhost:8000/speakers

-d "name=test&email=test@pycon.kr&organization_id=1"

{

"id": 1,

"name": "test",

"email": "test@pycon.kr",

"organization": {

"id": 1,

"name": "test organization"

}

}

DRF-YASG

DRF-YASG Custom Action
# main/views.py


queryset = Speaker.objects.all()


@action(methods=['get'], detail=False)

def count(self, _):

return Response({'result': Speaker.objects.count()})

Response schema  
!

# main/views.py


queryset = Speaker.objects


@swagger_auto_schema(

operation_description=' API',

responses={

'200': openapi.Response(

description='',

schema=openapi.Schema(

type='object',

properties={'result': openapi.Schema(type='integer')}

)

)

}

)


def count(self, _):


# main/views.py

class SpeakerCountSerializer(Serializer):

result = IntegerField()


queryset = Speaker.objects


@swagger_auto_schema(

operation_description=' API',

responses={'200': SpeakerCountSerializer}

)


def count(self, _):


DRF-YASG
●

○read_only, write_only

○serializer

●Redoc UI request

●Swagger UI

●OpenAPI Spec 2.0

DRF-YASG
●

○read_only, write_only

○serializer

●Redoc UI request

●Swagger UI

●OpenAPI Spec 2.0
https://swagger.io/blog/news/whats-new-in-openapi-3-0/

●Resource View get, post  
●arg parser View  
●field model marshal
Flask-RESTful
REST API OpenAPI Specification Python Web Apps & OAS Django Flask

●Flask-RESTful

○ Flask-RESTful API

● API

●Flask-RESTful
Flask-RESTPlus

●Flask RESTful Swagger 2.0

○ OpenAPI Spec 1.2

○ 2.0

●SQLAlchemy Flask RESTful Swagger (SAFRS)

○ DB model class

○ Model method docstring
API

Flask-RESTPlus


○ 2.0


○ DB model class

○ Model method docstring

Flask-RESTPlus


○ 2.0


○ DB model class

○ Model method docstring  
●Flask-RESTPlus

Flask-RESTPlus
from flask import Flask

from flask_sqlalchemy import SQLAlchemy

from flask_restplus import Api

app = Flask(__name__)

app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///db.sqlite3'

app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False

db = SQLAlchemy(app)

api = Api(app)


Flask-RESTPlus
class OrganizationModel(db.Model):

id = db.Column(db.Integer, primary_key=True, autoincrement=True)

name = db.Column(db.String(100), nullable=False)

class SpeakerModel(db.Model):

id = db.Column(db.Integer, primary_key=True, autoincrement=True)

name = db.Column(db.String(10), nullable=True)

email = db.Column(db.String(120), unique=True, nullable=False)

organization_id = db.Column(db.Integer, db.ForeignKey('organization_model.id'))

organization = relationship('OrganizationModel')

Flask-RESTPlus
organization_output = api.model('OrganizationOutput', {

'name': fields.String

})

speaker_output = api.model('SpeakerOutput', {

'name': fields.String,

'email': fields.String,

'organization': fields.Nested(organization_output)

})

speaker_input = reqparse.RequestParser()

speaker_input.add_argument('email', type=str)

speaker_input.add_argument('name', type=str)

speaker_input.add_argument('organization_id', type=int)


Flask-RESTPlus
@api.route('/speakers')

class Speaker(Resource):

@api.marshal_list_with(speaker_output)

def get(self):

return Speaker.query.all()

@api.expect(speaker_input)

@api.marshal_with(speaker_output)

def post(self):

args = speaker_input.parse_args()

speaker = SpeakerModel(**args)

db.session.add(speaker)

db.session.commit()

return speaker
$ curl -X POST localhost:5000/speakers

-d "name=test&email=test@pycon.kr&organization_id=1"

{

"name": "test",

"email": "test@pycon.kr",

"organization": {

"name": "test organization"

}

}

Flask-RESTPlus

PyCon Korea 2019 REST API Document Generation

●Web framework → OpenAPI YAML / JSON → Swagger / Redoc UI

● web framework(Bottle, Sanic, Vibora )  
runtime routing (path → view function)

○ OpenAPI schema

○ Sanic-RESTPlus

●drf-yasg, Flask-RESTPlus

www.aitrics.com
contact@aitrics.com
Yongseon Lee <yongseon@aitrics.com>
● REST API (Yongseon Lee)  
18th (Sun) 11:55 ~ 12:35
● Advanced Python testing techniques (Jaeman An) 
18th (Sun) 11:55 ~ 12:35
● Django Query Optimization (Soyoung Yoon) 
18th (Sun) 13:55 ~ 14:35
● Pickle & Custom Binary Serializer (Young Seok Kim) 
18th (Sun) 14:55 ~ 15:35
Talks from AITRICS

PyCon Korea 2019 REST API Document Generation

More Related Content

What's hot (20)

Similar to PyCon Korea 2019 REST API Document Generation (20)

Recently uploaded (20)

PyCon Korea 2019 REST API Document Generation