Skip to content

Commit

Permalink
New, add API descriptions and examples to OpenAPI spec (#1396)
Browse files Browse the repository at this point in the history 
* New, add API descriptions and example to OpenAPI spec

* Update flask_appbuilder/menu.py

Co-authored-by: Ville Brofeldt <33317356+villebro@users.noreply.github.com>

* Update flask_appbuilder/security/api.py

Co-authored-by: Ville Brofeldt <33317356+villebro@users.noreply.github.com>

* More descriptions for the spec

Co-authored-by: Ville Brofeldt <33317356+villebro@users.noreply.github.com>
  • Loading branch information
@dpgaspar @villebro
dpgaspar and villebro authored Jun 30, 2020
1 parent 670f7f2 commit 1725552
Show file tree
Hide file tree
Showing 4 changed files with 98 additions and 4 deletions.
76 changes: 73 additions & 3 deletions flask_appbuilder/api/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1241,6 +1241,8 @@ def info(self, **kwargs):
""" Endpoint that renders a response for CRUD REST meta data
---
get:
description: >-
Get metadata information about this API resource
parameters:
- in: query
name: q
Expand All @@ -1262,7 +1264,22 @@ def info(self, **kwargs):
type: object
filters:
type: object
properties:
column_name:
type: array
items:
type: object
properties:
name:
description: >-
The filter name. Will be translated by babel
type: string
operator:
description: >-
The filter operation key to use on list filters
type: string
permissions:
description: The user permissions for this API resource
type: array
items:
type: string
Expand Down Expand Up @@ -1322,6 +1339,8 @@ def get(self, pk, **kwargs):
"""Get item from Model
---
get:
description: >-
Get an item model
parameters:
- in: path
schema:
Expand All @@ -1343,15 +1362,36 @@ def get(self, pk, **kwargs):
properties:
label_columns:
type: object
properties:
column_name:
description: >-
The label for the column name.
Will be translated by babel
example: A Nice label for the column
type: string
show_columns:
description: >-
A list of columns
type: array
items:
type: string
description_columns:
type: object
properties:
column_name:
description: >-
The description for the column name.
Will be translated by babel
example: A Nice description for the column
type: string
show_title:
description: >-
A title to render.
Will be translated by babel
example: Show Item Details
type: string
id:
description: The item id
type: string
result:
$ref: '#/components/schemas/{{self.__class__.__name__}}.get'
Expand Down Expand Up @@ -1431,6 +1471,8 @@ def get_list(self, **kwargs):
"""Get list of items from Model
---
get:
description: >-
Get a list of models
parameters:
- in: query
name: q
Expand All @@ -1448,28 +1490,56 @@ def get_list(self, **kwargs):
properties:
label_columns:
type: object
properties:
column_name:
description: >-
The label for the column name.
Will be translated by babel
example: A Nice label for the column
type: string
list_columns:
description: >-
A list of columns
type: array
items:
type: string
description_columns:
type: object
properties:
column_name:
description: >-
The description for the column name.
Will be translated by babel
example: A Nice description for the column
type: string
list_title:
description: >-
A title to render.
Will be translated by babel
example: List Items
type: string
ids:
description: >-
A list of item ids, useful when you don't know the column id
type: array
items:
type: string
count:
description: >-
The total record count on the backend
type: number
order_columns:
description: >-
A list of allowed columns to sort
type: array
items:
type: string
result:
type: array
items:
$ref: '#/components/schemas/{{self.__class__.__name__}}.get_list' # noqa
description: >-
The result from the get list query
type: array
items:
$ref: '#/components/schemas/{{self.__class__.__name__}}.get_list' # noqa
400:
$ref: '#/components/responses/400'
401:
Expand Down
4 changes: 3 additions & 1 deletion flask_appbuilder/api/manager.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,14 +20,16 @@ def get(self, version):
to a certain version
---
get:
description: >-
Get the OpenAPI spec for a specific API version
parameters:
- in: path
schema:
type: string
name: version
responses:
200:
description: Item from Model
description: The OpenAPI spec
content:
application/json:
schema:
Expand Down
9 changes: 9 additions & 0 deletions flask_appbuilder/menu.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -170,6 +170,9 @@ def get_menu_data(self):
"""An endpoint for retreiving the menu.
---
get:
description: >-
Get the menu data structure.
Returns a forest like structure with the menu the user has access to
responses:
200:
description: Get menu data
Expand All @@ -179,17 +182,23 @@ def get_menu_data(self):
type: object
properties:
result:
description: Menu items in a forest like data structure
type: array
items:
type: object
properties:
name:
description: >-
The internal menu item name, maps to permission_name
type: string
label:
description: Pretty name for the menu item
type: string
icon:
description: Icon name to show for this menu item
type: string
url:
description: The URL for the menu item
type: string
childs:
type: array
Expand Down
13 changes: 13 additions & 0 deletions flask_appbuilder/security/api.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,8 @@ def login(self):
"""Login endpoint for the API returns a JWT and optionally a refresh token
---
post:
description: >-
Authenticate and get a JWT access and refresh token
requestBody:
required: true
content:
Expand All @@ -46,15 +48,23 @@ def login(self):
type: object
properties:
username:
description: The username for authentication
example: admin
type: string
password:
description: The password for authentication
example: complex-password
type: string
provider:
description: Choose an authentication provider
example: db
type: string
enum:
- db
- ldap
refresh:
description: If true a refresh token is provided also
example: true
type: boolean
responses:
200:
Expand Down Expand Up @@ -115,6 +125,8 @@ def refresh(self):
token without forcing the user to login again
---
post:
description: >-
Use the refresh token to get a new JWT access token
responses:
200:
description: Refresh Successful
Expand All @@ -124,6 +136,7 @@ def refresh(self):
type: object
properties:
access_token:
description: A new refreshed access token
type: string
401:
$ref: '#/components/responses/401'
Expand Down

0 comments on commit 1725552

Please sign in to comment.