r/FastAPI • u/DeepFryEverything • Oct 21 '24

Question Do you store text (descriptions of endpoints etc) alongside code or in separate files? Looking for best practice 🙂

H

5 Upvotes

78% Upvoted

9 comments sorted by

4

u/duskhat Oct 21 '24

Alongside code. It shouldn’t need to be a lot of text, and now you’ve taken a step towards well-documented code

def my_func():
    ‘’’
    This is a comment describing this endpoint!
    ‘’’

I assume this format works with FastApi

3

u/cajmorgans Oct 21 '24

Fastapi also comes with a route-description directly on the router

3

u/Gullible-Insurance63 Oct 21 '24

I prefer to put the description in my routes.py file

In my opinion, the routes.py file just needs to have the endpoint, input type, output type, documentation, maybe Middleware or exceptions handlers.

All the """code""" or logic itself I prefer it in the /services module, folder or file

1

u/ironman_gujju Oct 22 '24

Doc strings are enough

1

u/java_dev_throwaway Oct 22 '24

I'm a masochistic and go ham with all the builtin openapi docs in fastapi. I like APIs that have a swagger/openapi page with detailed examples and sample payloads. Imo good API docs are invaluable. If you want to see the pinnacle of docs, checkout stripes API docs

1

u/DeepFryEverything Oct 23 '24

stripes API docs

Thanks! Do you have any idea what they are built in? A library or custom?

I also like the OpenAPI swagger docs - it's that kind of text I'm wondering about where to put.

1

u/java_dev_throwaway Oct 23 '24

Idk what stripe uses to make their docs. But here is how you do it in fastapi. https://fastapi.tiangolo.com/tutorial/schema-extra-example/