Arquivos Estáticos em FastAPI

Para criar interfaces de interação com o servidor, é comum utilizar páginas HTML. Essas páginas são compostas por arquivos estáticos que contêm código HTML e frequentemente incluem outros recursos estáticos, como estilos CSS, imagens ou scripts JavaScript. O FastAPI oferece uma solução prática e eficiente para gerenciar arquivos estáticos por meio do módulo fastapi.staticfiles.

StaticFiles(directory=None, packages=None, html=False, check_dir=True)

Parâmetros da Classe StaticFiles:

directory: Especifica o caminho do diretório onde os arquivos estáticos estão localizados.
packages: Lista de pacotes Python (como strings ou tuplas de strings) de onde os arquivos estáticos podem ser servidos.
html: Quando definido como True, o servidor opera no "modo HTML". Nesse caso, ao acessar a raiz do diretório configurado, o arquivo index.html será enviado automaticamente (se estiver presente).
check_dir: Garante que o diretório especificado existe no momento da inicialização.

A seguir, veja um exemplo prático de como utilizar esse recurso. Considere a seguinte estrutura de projeto:

.
├── public
│   └── index.html
├── main.py

O diretório public foi criado para armazenar arquivos estáticos. Dentro dele, adicionamos um arquivo index.html com o seguinte conteúdo:

<!DOCTYPE html>
<html>
  <head>
    <title>Exemplo FastAPI</title>
    <meta charset="utf-8" />
  </head>
  <body>
    <h2>Olá, mundo!</h2>
  </body>
</html>

No arquivo main.py, configuramos o serviço de arquivos estáticos com o seguinte código:

from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles

app = FastAPI()

app.mount("/static", StaticFiles(directory="public"))

Para trabalhar com arquivos estáticos, primeiro importamos a classe StaticFiles. Em seguida, criamos o objeto da aplicação FastAPI e chamamos o método mount().

O método mount() configura um objeto para lidar com as requisições em uma rota específica. Neste caso, para requisições feitas no endereço /static, o objeto responsável é o StaticFiles, que, por meio do parâmetro directory, define o diretório /public como o local onde os arquivos estáticos estão armazenados (o nome do diretório pode ser qualquer um, conforme sua escolha).

Ao acessar http://127.0.0.1:8000/static/index.html, a aplicação responderá com o arquivo index.html armazenado no diretório public.

Exemplo de arquivos estáticos no FastAPI, exibindo a mensagem 'Olá, mundo!' ao acessar http://127.0.0.1:8000/static/index.html

Dessa forma, podemos adicionar outros arquivos estáticos ao diretório public e acessá-los por meio da rota /static.

Configurando uma Página Inicial

Muitas aplicações web possuem uma página inicial que é carregada automaticamente ao acessar a raiz do site. A classe StaticFiles permite configurar esse comportamento por meio do parâmetro html. Quando configurado como True, o servidor buscará e enviará automaticamente o arquivo index.html caso o nome do arquivo não seja especificado na URL.

Atualize o código no arquivo main.py para o seguinte:

from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles

app = FastAPI()

app.mount("/static", StaticFiles(directory="public", html=True))

Com esta configuração, ao acessar http://127.0.0.1:8000/static/, o servidor enviará automaticamente a página index.html, mesmo sem o nome do arquivo especificado na URL.

Exemplo de arquivos estáticos no FastAPI, exibindo a mensagem 'Olá, mundo!' ao acessar http://127.0.0.1:8000/static/

Configurando a Página Inicial para Toda a Aplicação

Se for necessário configurar o diretório de arquivos estáticos como a raiz de toda a aplicação, de modo que o arquivo index.html seja carregado automaticamente ao acessar a aplicação, podemos ajustar o código da seguinte forma:

from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles

app = FastAPI()

app.mount("/", StaticFiles(directory="public", html=True))

Com essa configuração, ao acessar http://127.0.0.1:8000/, o servidor enviará diretamente o arquivo index.html do diretório public.

Documentação oficial:

Arquivos Estáticos no FastAPI