docstrings

[mullenkamp]

What is the proper way to write docstrings for the swagger UI to render them properly?
I've written the docstrings in the normal rst python way...but they aren't formatted properly in the swagger UI.

And more broadly, what's the appropriate way to create and publish documentation about the APIs in FastAPI?

Thanks.

[Tert0]

You can use Markdown (MD).
A Doc-String like this

"""
    # A Header
    **bold**
    *italic*
    ## Smaller Header
   `` `
   a multiline code block
   `` `
   `a inline codeblock` Lorem Ipsum
"""
#  You have to remove the space from "`` `"

looks like this:

[ghandic]

Great answer @Tert0 I didn't know this! @mullenkamp is this answer sufficient? If so could you mark as answered

[mullenkamp]

Yes indeed. Thank you.

[belalmuflih]

this actually didn't work for me.

description =
"""
thisAPI helps you to easily integrate your system 👨‍💻🚀!

## Coupon

You can **validate usability**.

## Password

You can **update password**.

## User

You can **create token**.
You can **update language**.
You can **delete token**.

## Invoice

You can **create invoice**.
You can **return invoice**.
* You can **bulk create invoice**. (_not implemented_)

## Points

You can **grant points to users**.

## Sales

You can **read sales_report**.
You can **read sales_statement**.

## Auth

You will be able to:

* **Request login** (_not implemented_in_docs).

"""

app = FastAPI(
title=settings.TITLE,
docs_url=settings.DOCS_URL,
redoc_url=settings.REDOC_URL,
description=description,
lifespan=lifespan,
)

does anyone have any idea about this?

[Tert0]

You are using a code block (tripple backticks ```) inside your description.
Without this code block: https://gist.github.com/Tert0/c09238372ae39ec2ef4c3cffae13ff20
It renders the markdown:

[belalmuflih]

Turns out my issues was the the tabs before the text. Thanks a lot your solution helped! <3

[codebydant]

That would be ok for swagger, but if you are using a specific docstring style for external docs such as sphinx, I don´t think this approach will work. Is there a way to instruct swagger to ignore python docstrings?

[claytonEtillman]

@dtcMLOps, you can put \f in the docstring and FastAPI will stop rendering from the docstring at that point. https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#advanced-description-from-docstring

[claytonEtillman]

You can also add a MarkDown string to the metadata for the entire app. This should not interfere with any external docs as it's not a docstring. https://fastapi.tiangolo.com/tutorial/metadata/?h=apirouter#metadata-for-api

[phobson]

Just a quick note about triple backticked-sections.

If you use textwrap.dedent on the docstring, it renders better:

@router.get(
    "/{data_source}/inst_vals",
    summary="Instanteousd (raw) observations",
    description=dedent(f"""\
    ## Instanteous time series observations

    This returns a *paginated* response of time series data series directly from the data warehouse
    (i.e., raw & unrounded/unaggregated timesteps).
    The default page size is 500,000 rows. Page sizes of up to 1,000,000
    can work.

    The response of a call includes a "next_params" item.
    When there is more data to be retrieved, that item contains the
    dictionary you need to pass `requests.get` to recieve the page.
    When there are no more pages of data to recieve, "next_params" will be `None`

    {data_source_note}

    ### Python example

    ```python
    import requests
    import pandas
    baseurl = "{_docstring_baseurl}"
    route = "",
    query_params = {{
        "file_stem": "KATL",
        "parameter": None,
        "start_date": "2010-10-01",
        "end_date": "2022-09-30",
        "timezone": "US/Pacific",
        "limit": 500_000,  # page size
    }}

    rows = []
    while query_params is not None:
        response = requests.get(f"{{baseurl}}/ts/wx/inst_vals", params=query_params)
        assert response.ok
        data = response.json()
        rows.append(data["results"])

        # now replace the old query params with the response's "next_params"
        # eventually this will be set to None and you'll kick out of the loop

        query_params = data["next_params"]

    df = pandas.DataFrame(rows)

    ```

    ### R Example
    ```R
    # TDB
    ```
    """)
)
def get_inst_vals():
    pass

And I get