Are there any api developer docs?

[joe-eklund]

First check

• I used the GitHub search to find a similar issue and didn't find it.
• I searched the FastAPI documentation, with the integrated search.
• I already searched in Google "How to X in FastAPI" and didn't find any information.

Description

What I mean by api developer docs are basically something like sphinx docs for function definitions. This is usually generated from function docstrings (which I didn't see any in my small amount of browsing the FastAPI codebase). For example, here are the docs for github3 https://github3py.readthedocs.io/en/master/api-reference/index.html. It is an easy way to click through the entire package and see class and function definitions.

Does FastAPI have these? The tutorial docs look pretty good, but sometimes I just want to know what all the function parameters are independent of the context in a tutorial.

[tiangolo]

Not yet. I expect to use https://github.com/tomchristie/mkautodoc at some point.

But first I have to clean up some of the parameters, define a docstring style, and add docstrings everywhere.

[nsidnev]

@tiangolo
Hi! Just out of interest, but what do you think about using pawamoy/mkdocstrings? I recently used this project and it worked without any problems.

[joe-eklund]

I have used https://www.sphinx-doc.org/en/master/ before and they look pretty nice. Works very well for Python code in my opinion.

[dbanty]

@tiangolo if you were able to define a docstring style I'd be happy to start contributing some notes. I habitually check documentation in my IDE and would love to have some quick references available for FastAPI.

As far as picking a style, of course the mk tools want the docstrings to be in Markdown. Unfortunately PyCharm won't render / extract any useful information from the docstrings unless they are in one of it's supported formats (e.g. reStructuredText, Epytext) none of which use Markdown to my knowledge. Maybe that won't matter though because markdown is so easy to read unrendered.

[falkben]

I would also be happy to contribute once a style is finalized. I believe this is also missing in starlette...

[pawamoy]

@dbanty good point about PyCharm being able to handle docstrings or not. In my experience, it handles Google-style docstrings in Markdown pretty well. You can set it up in the Tools -> Python integrated tools -> Docstrings format -> Google. PyCharm will match parameters in the signature with the ones documented in the docstrings, warn you when some are missing from the docstring, or inversely, etc.

[dbanty]

@pawamoy yes it does! As you know I've recently started using your mkdocstrings for documenting a project. I've been using those Google-style docstrings and combining auto-generated API docs with manual docs which are inspired by (and therefore very similar to
) FastAPI's. Been working pretty well so far.

mkdocstrings definitely gets my endorsement for an option here.

[reillysiemens]

@tiangolo: My team and I have been evaluating FastAPI for use at our workplace, but the lack of API-level documentation for developers has caused a little friction for adoption. Is there something still blocking the decision to use mkautodoc, mkdocstrings, the classic Sphinx with reStructuredText, or some other option?

[Kludex]

At the point the issue was created mkdocstrings was just a POC, now it's more mature. I've seen people asking for it on gitter. What do you think @tiangolo ?

[adamcunnington]

It is kind of insane that this project does not have API documentation. It is the single thing stopping me from using fastapi right now which otherwise looks awesome!

I started a project and straight away found that the MAIN object, fastapi.FastAPI() is not documented explicitly and this just put me off. To find out how to set a root path, I had to dig around in the source code. PLEASE fix this. It looks like several community members have tried to help but tiangolo is pushing back, waiting for perfection. Don't - just submit some auto-generated docs and iterate on it later. Something is better than nothing!

[Kludex]

To find out how to set a root path, I had to dig around in the source code.

All the features are documented. I don't see how this is a blocking point for you to use FastAPI.

But I understand your point, @adamcunnington .

@tiangolo Is already aware this is a wanted feature. Also, to put your mind at ease, he told me that he's going to have some time soon to merge and work on lots of PRs, so stay tuned for good news about this! :)

[adamcunnington]

The point is I didn't even know it was called root_path in order to search for it. I needed to see documentation for the fastapi.FastAPI() object to even determine this - which took me to the source code.

Glad it's high on the list.

[yifeikong]

Please fix this, lack of API reference is such a painful situation for users.

It seems that there is a open PR for this. For anyone looking for it, you can preview the API reference by the comments in this PR: #2275

[r-priyam]

@tiangolo Any guesses that when we are going to see this? It's been 2 years now

[frerikandriessen]

I just want to add that I'm also very interested in this, and that I am also happy to contribute by adding docstrings wherever they are still missing.

[orlandodiaz]

just came back from google to find this open issue. please add this

[septatrix]

Also there seem to be some parts which are not even documented in docstrings like the debug argument of the FastAPI constructor

[mcrapts]

I think this is a must have. The tutorials on the website are nice, but they are not documentation in my opinion.

[alejoar]

This really needs to get done to be taken seriously by any developer team.

[sorressean]

Is this still pending? This is a huge project and others keep getting work. The tutorial is okay, but I know how to use parts of fastapi and just want a reference.

[pawamoy]

I deployed API references of FastAPI here: https://pawamoy.github.io/fastapi-ref/, built with mkdocstrings. It's not up to date, I can regenerate it if needed. I think it gives a nice preview of what's possible. It just needs more docstrings :)

[acidjunk]

@pawamoy the deploy serves a 404 for me: https://pawamoy.github.io/fastapi
?

[septatrix]

@pawamoy the deploy serves a 404 for me: https://pawamoy.github.io/fastapi ?

There is also a -ref at the end of the URL which you seem to be missing

[acidjunk]

To clarify: The first link on that page, serves a 404:

[septatrix]

Ah I see, but you can still use the links in the sidebar on the left

[acidjunk]

Yes; I know AND I like these kind of docs. 🚀

I think it's very helpful (although I often rely on my IDE to find this kind of stuff.)

[pawamoy]

Yeah the link in the README, and therefore the index page of the docs, is wrong 😅
I'll fix it 🙂

[tiangolo]

Quick update. I want to have this and I want to do it properly.

I'm not happy with the state of docstrings in Python in general. There are too many micro-syntax formats that need to be custom parsed by anything that provides support for them, they don't have autocompletion, inline errors, etc.

That's something I want to work (and I have been working) on to improve, in Python, in general. We'll see how it goes.

And in the end, it will (most probably 🤞 ) be integrated and supported by @pawamoy's mkdocstrings, it will be part of the FastAPI docs, and hopefully, this new thing will also be supported by the main editors too (I'm already in conversations with the PyCharm and VS Code teams).

Not much more to say, but just to let you all know that I know about this, and it's indeed in the backlog. But I want to do it properly. 🤓

[JarroVGIT]

To be honest @tiangolo, I think there are plenty of people that are willing to put in the work to have at least something. It kinda sounds like you want to fix the whole docstring problem in Python, before we get proper docstring support in FastAPI.

Would it be an idea to pick one now (doesn't matter wether it is Google, Numpydoc, Epytext or reST), just so we can start on providing the actual text? Then when you have created a new standard (?) for docstrings, we can reformat them to that if required.

It just seem that this is quite an ambition for putting of a very useful feature of the project. It's already fully typed, let's make it fully doc'ed as well :)

[septatrix]

I definitely agree with @JarroVGIT in that it is currently more important to get a MVP than creating a whole new standard à la XKCD. I would already be more than happy if this project would for now just adopt/provide the docs generated by @pawamoy above.

While there might not be precise descriptions of every parameter it at least gives a great overview of which methods are available at all. Currently I get all of my documentation from reading the source which is not ideal...

Nevertheless I am still intrigued into what you plan for improving docstrings is 🤔

[wookasz]

@tiangolo don't let perfect be the enemy of good. Documentation seems to be a huge ask and it's currently one of the primary reasons why I'm getting pushback against migrating to fastapi.

This issue is now open for over 3 years with nothing to show for it. Add something, anything, then iterate to get it to the state you want it in.