Documenting endpoint parameters (OpenAPI)

Every codops exposes its endpoints through a gateway that publishes an OpenAPI (Swagger) specification. The gateway reads request parameters itself and hands them to your function, so the specification would not list them on its own. PEACH therefore fills the parameters in for you, and lets you override them in peach.conf.

This page applies to endpoints defined with the notebook + peach.conf route (see Recommendation API).

Automatic parameters

If an endpoint has no openapi_extra key, PEACH reads the signature of each component method at build time and documents its arguments as optional query parameters. Your code is parsed, never executed.

def endpoint(u: str = None, random: bool = False, size: int = 10):
    ...

is documented as:

Parameter	Type	Default
u	string
random	boolean	false
size	integer	10

Rules:

• str, int, float, bool, list and dict map to the matching OpenAPI type. Optional[int] and int | None are treated as int. Any other annotation, or none, leaves the type unspecified.
• A literal default value is shown as the parameter default.
• All parameters are optional: a missing parameter is replaced by its default (or None) before your function is called.
• model and debug are provided by the platform and are not listed. self, *args and **kwargs are ignored.
• If the endpoint has several components, or a fallback, the parameters of all of them are combined. When the same name appears more than once, the first declaration wins (components first, then the fallback).
• If the code cannot be parsed, no parameters are generated and the build is not affected.

Declaring parameters yourself

Add openapi_extra to the endpoint to replace the automatic result. It is passed to the OpenAPI operation as is, so it follows the OpenAPI parameter object format:

codops: default
endpoints:
  my_endpoint:
    url: /my/endpoint
    components:
      main:
        notebook: notebooks/my.ipynb
        method: endpoint
    openapi_extra:
      parameters:
        - name: user_id
          in: query
          required: true
          description: Identifier of the user to recommend for
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 10

Note

When openapi_extra is present, nothing is derived from the code, even if the value is empty. Use openapi_extra: {} to turn the automatic parameters off for an endpoint.

Documentation only

openapi_extra changes what the specification shows. It does not validate requests or change which arguments your function receives. To reject bad input, use validate_input: true on the component.

GET and POST

Endpoints accept both GET and POST. Automatic parameters are query parameters, which work for both in the Swagger interface. If your POST endpoint is meant to receive a JSON body, describe it with a requestBody in openapi_extra:

    openapi_extra:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id: {type: string}

Turning Swagger off

The interactive documentation (/docs), the ReDoc page (/redoc) and the specification itself (/openapi.json) are on by default. To switch all three off for a codops, set the environment variable DISABLE_SWAGGER to true on its gateway:

DISABLE_SWAGGER=true

• Only the value true turns them off (case does not matter). If the variable is unset, or has any other value, they stay on.
• The setting covers the whole codops, not a single endpoint, because all endpoints of a codops share one gateway.
• The three paths then answer 404. Your endpoints keep working exactly as before.
• It is read when the gateway starts, so a change takes effect after the gateway is redeployed.

When does it apply?

The specification is generated when the codops is built, so a change to a function signature or to openapi_extra shows up after the next deployment of your repository. It needs a platform release that includes this feature; endpoints keep working exactly as before either way.