Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

OpenAPI v3.0: Add Security Scheme info #61

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

OpenAPI v3.0: Add Security Scheme info #61

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ec557f0
OpenAPI v3.0: Add Security Scheme info
mhuin Sep 2, 2019
9b9dbb8
Security Schemes support: add testing, fix errors
mhuin Oct 11, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 110 additions & 2 deletions sphinxcontrib/openapi/openapi30.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -225,13 +225,25 @@ def _example(media_type_objects, method=None, endpoint=None, status=None,
yield ''


def _find_scope_description(scope, securityScheme):
desc = 'No description available'
for flow in securityScheme['flows']:
for sc in securityScheme['flows'][flow]['scopes']:
if sc == scope:
desc = securityScheme['flows'][flow]['scopes'][sc]
break
return desc


def _httpresource(endpoint, method, properties, convert, render_examples,
render_request):
render_request, components=None):
# https://github.com/OAI/OpenAPI-Specification/blob/3.0.2/versions/3.0.0.md#operation-object
parameters = properties.get('parameters', [])
responses = properties['responses']
indent = ' '

components = components or {}

yield '.. http:{0}:: {1}'.format(method, endpoint)
yield ' :synopsis: {0}'.format(properties.get('summary', 'null'))
yield ''
Expand All @@ -246,6 +258,61 @@ def _httpresource(endpoint, method, properties, convert, render_examples,
yield '{indent}{line}'.format(**locals())
yield ''

securities = properties.get('security', [])
for security in securities:
yield ('{indent}This resource requires the '
'following authentication scheme(s):').format(**locals())
yield ''
for ref in security.keys():
secScheme = components.get('securitySchemes', {}).get(ref, {})
yield ('{indent}:scheme: ' + ref).format(**locals())
if secScheme['type'] == 'http':
if secScheme['scheme'].lower() == 'basic':
line = ':security: HTTP Basic'
yield '{indent}{line}'.format(**locals())
elif secScheme['scheme'].lower() == 'bearer':
line = ':security: HTTP Bearer'
yield '{indent}{line}'.format(**locals())
else:
raise Exception(
'Unknown http scheme "%s"' % secScheme['scheme'])
elif secScheme['type'] == 'apiKey':
key_loc = secScheme['in']
yield ('{indent}:security: '
'API key in {key_loc}').format(**locals())
elif secScheme['type'] == 'openIdConnect':
yield ('{indent}:security: '
'OpenID Connect').format(**locals())
if secScheme.get('openIdConnectUrl'):
discoveryUrl = secScheme.get('openIdConnectUrl')
yield ('{indent}{indent}'
'Discovery URL: {discoveryUrl}').format(**locals())
yield ''
yield '{indent}{indent}Scope(s):'.format(**locals())
for scope in security[ref]:
yield ('{indent}{indent}'
'{indent}:scope {scope}:').format(**locals())
elif secScheme['type'] == 'oauth2':
yield '{indent}:security: OAuth 2.0'.format(**locals())
if 'description' in secScheme:
desc = secScheme['description']
else:
desc = 'No description available'
yield '{indent}{indent}{desc}'.format(**locals())
yield ''
yield '{indent}{indent}Scope(s):'.format(**locals())
for scope in security[ref]:
yield ('{indent}{indent}'
'{indent}:scope {scope}:').format(**locals())
# find the scope description
scope_desc = _find_scope_description(scope, secScheme)
yield ('{indent}{indent}{indent}'
'{indent}' + scope_desc).format(**locals())
else:
raise Exception(
'Unknown security scheme "%s"' % secScheme['type'])
yield ''

# print request's path params
for param in filter(lambda p: p['in'] == 'path', parameters):
yield indent + ':param {type} {name}:'.format(
Expand All @@ -264,6 +331,18 @@ def _httpresource(endpoint, method, properties, convert, render_examples,
yield '{indent}{indent}{line}'.format(**locals())
if param.get('required', False):
yield '{indent}{indent}(Required)'.format(**locals())
# security params
securities = properties.get('security', [])
for security in securities:
for ref in security.keys():
secScheme = components.get('securitySchemes', {}).get(ref, {})
if secScheme['type'] == 'apiKey':
if secScheme['in'] == 'query':
yield indent + ':query {type} {name}:'.format(
type='string',
name=secScheme['name'])
yield ('{indent}{indent}(Required'
' by authentication "{ref}")').format(**locals())

# print request content
if render_request:
Expand Down Expand Up @@ -307,6 +386,34 @@ def _httpresource(endpoint, method, properties, convert, render_examples,
yield '{indent}{indent}{line}'.format(**locals())
if param.get('required', False):
yield '{indent}{indent}(Required)'.format(**locals())
# security header params
securities = properties.get('security', [])
for security in securities:
for ref in security.keys():
secScheme = components.get('securitySchemes', {}).get(ref, {})
# bearer auth
if secScheme['type'] == 'http' and\
secScheme.get('scheme') == 'bearer':
yield indent + ':reqheader Authorization:'
yield '{indent}{indent}Bearer <token>'.format(**locals())
yield ('{indent}{indent}(Required '
'by security scheme "{ref}")'.format(**locals()))
# API key header
elif (secScheme['type'] == 'apiKey' and
secScheme.get('in') == 'header'):
sechead_name = secScheme['name']
yield indent + ':reqheader {sechead_name}:'.format(**locals())
yield ('{indent}{indent}(Required '
'by security scheme "{ref}")'.format(**locals()))
# API key cookie
elif (secScheme['type'] == 'apiKey' and
secScheme.get('in') == 'cookie'):
cookie_name = secScheme['name']
yield indent + ':reqheader Cookie:'
yield ('{indent}{indent}'
'{cookie_name}=<API key>').format(**locals())
yield ('{indent}{indent}(Required '
'by security scheme "{ref}")').format(**locals())

# print response headers
for status, response in responses.items():
Expand Down Expand Up @@ -399,6 +506,7 @@ def openapihttpdomain(spec, **options):
properties,
convert,
render_examples='examples' in options,
render_request=render_request))
render_request=render_request,
components=spec.get('components', {})))

return iter(itertools.chain(*generators))
Loading