The directory structure

Swagger importance

Design API before getting to work

Basic information

Inside the swagger folder create a sub-folder for your endpoint

swagger/myexample

Create a specs.yaml file containing the configuration of the endpoint and then a yaml file for each allowed method (get, post, put, delete)

The specs file

depends_on:
    - ENV_VAR

file:the python file (inside apis folder) containing the implementation of the endpoint.MANDATORY

class: the python class (in the python file) implementing the endpoint.MANDATORY

schema:
    expose: true|false

baseuri: "/api" | "/auth"OPTIONAL

mapping:
    yourcustomlabel: /your/mapping
    yourcustomlabel2: /your/mapping/<mapid>

ids:
    mapid: description <- I found this in profile/specs.yaml but never used it

labels:
    - your
    - labels

The methods file

get.yaml

post.yaml

put.yaml

delete.yaml

Specify configuration for a specific method. Configuration are relative to mapping by using the same label(s) configured in the specs file. A common block allows to create a configuration inherited from all mappings configuration

label:
    custom:
       publish: true\|false
       authentication: true\|false
    summary: description
    respones:
      'code':
          description: Describe when this code will occur

Examples

specs.yaml:

file: myendpointfile
class: MyEndpointClass
mapping:
        getall: /myres
        getone: /myres/<id>

get.yaml

common:
    custom:
        authentication: true

getall:
    summary: Return all resources

getone:
    summary: Return the resource identified by the given id

Parameters

Write some short intro to parameters

Query parameters

As in swagger

label:
    parameters:
        - name: yourparameter
          description: Your parameter description
          in: query
          type: string|...
          required: true|false

Formdata parameters

As in swagger

label:
    parameters:
        - name: yourparameter
          description: Your parameter description
          in: formData          
          type: string|...
          required: true|false              
          custom:
              options only used for formly integration (view frontend development)

Body parameters

As in swagger. Schema are defined in models/swagger.yaml

label:
    parameters:
        - name: yourparameter
          in: body
          schema:
              $ref: "#/definitions/ProfileUpdate"

Custom parameters

CustomParameterBlock are defined in models/swagger.yaml under the section FormDataParameters

label:
    custom_parameters:
        - CustomParameterBlock

Headers parameters

...

Path parameters

...