Adiciona página com documentação da API

api/docs/views.py

@@ -0,0 +1,12 @@
+from django.conf import settings
+from django.shortcuts import render
+
+from core.models import Dataset
+
+
+def dynamic_api_docs_view(request):
+    context = {
+        "datasets": Dataset.objects.api_visible(),
+        "api_host": settings.BRASILIO_API_HOST,
+    }
+    return render(request, "api/docs.html", context=context)

api/templates/api/docs.html

@@ -0,0 +1,47 @@
+{% extends "base.html" %}
+
+{% block title %}Documentação da API{% endblock %}
+
+{% block content %}
+
+<div class="section">
+  <div class="row">
+      <div class="col s12">
+        <div class="card">
+          <div class="card-content">
+            <p class="card-title">Documentação da API</p>
+            <p>Aqui você pode encontrar a listagem de todos os datasets, tabelas e campos disponíveis na API do Brasil.io. Além disso, você também encontrará informações sobre como fazer requisições para a API respeitando a autenticação.</p>
+            <p><b>Importante:</b> Utilizar a API desnecessariamente e de maneira não otimizada onera muito nossos servidores e atrapalha a experiência de outros usuários. Por conta disso, nessa documentação vocè também encontrará os links para os arquivos de dados completos de todos os datasets.</p>
+
+            <br/>
+            <p class="card-title">Índice</p>
+            <ul>
+              <li><a href="#autenticacao">Autenticação</a></li>
+              <li><a href="#datasets">Datasets</a></li>
+            {% for dataset in datasets %}
+              <li><a href="#{{ dataset.slug }}">{{ dataset.name }}</a></li>
+            {% endfor %}
+            </ul>
+          </div>
+        </div>
+      </div>
+  </div>
+
+  <h3 id="autenticacao">Autenticação</h3>
+  <hr>
+  <p>Para ter mais contexto sobre os porquês dessa autenticação, leia o nosso blogpost <a href="https://blog.brasil.io/2020/10/31/nossa-api-sera-obrigatoriamente-autenticada/" target="_blank">"Nossa API será obrigatoriamente autenticada"</a>.</p>
+  <p>A API do Brasil.IO implementa utilizando o <b>cabeçalho HTTP Authorizaton</b>. Ela espera que o valor desse cabeçalho seja sempre algo no formato <code>Token sua_chave_de_api_aqui</code>. Este é um exemplo de uma requisição para a raiz da API utilizando o Curl:</p>
+  <p><code>curl -X GET -k -H 'Authorization: Token 123412341234' -i 'https://api.brasil.io/v1/'</code></p>
+  <p>Para criar e gerenciar suas chaves de API, autentique-se no sistema e acesse a página <a href="{% url 'brasilio_auth:list_api_tokens' %}">Chaves da API</a>.</p>
+
+  <h3 id="datasets">Datasets</h3>
+  <hr>
+  <p>Exemplo de requisição para listar todos os datasets disponíveis na API do Brasil.io:</p>
+  <p><code>curl -X GET -k -H 'Authorization: Token 123412341234' -i 'https://{{ api_host }}/v1/datasets/'</code></p>
+
+  {% for dataset in datasets %}
+    {% include "api/snippets/dataset_docs.html" with dataset=dataset %}
+  {% endfor %}
+
+  </div>
+{% endblock %}

api/templates/api/snippets/dataset_docs.html

@@ -0,0 +1,37 @@
+<h4 id="{{ dataset.slug }}">{{ dataset.name }}</h4>
+<hr/>
+
+<p>Exemplo de requisição para apresentar informações sobre esse dataset:</p>
+<p><code>curl -X GET -k -H 'Authorization: Token 123412341234' -i 'https://{{ api_host }}/v1/dataset/{{ dataset.slug }}/'</code></p>
+<p>O <b>dataset completo</b> pode ser baixado diretamente <a href="{{ dataset.files_url }}">nesta página</a>. Por favor, dê preferência a baixar o dataset completo caso você vá precisar de todos aos dados ao invés de utilizar a API.</p>
+
+{% for table in dataset.tables %}
+  {% if table.api_enabled %}
+  <h5 id="{{ dataset.slug }}-{{ dataset.table }}">Tabela {{ table.name }}</h5>
+  <p>Exemplo de requisição para os dados desta tabela:</p>
+  <p><code>curl -X GET -k -H 'Authorization: Token 123412341234' -i 'https://{{ api_host }}/v1/dataset/{{ dataset.slug }}/{{ table.name }}/data/'</code></p>
+  <h6>Colunas</h6>
+
+  <ul class="table-fields">
+    {% for field in table.fields %}
+        <li><code>{{ field.name }}</code> ({{ field.get_type_display }})
+
+        {% if field.show %}
+          {% if field.show_on_frontend %}<i class="fa fa-eye" title="Esse campo é visível na interface Web, na API e no download completo"></i>{% endif %}
+          {% if not field.show_on_frontend %}<i class="fa fa-low-vision" title="Esse campo não é visível na interface Web, apenas na API e no download completo"></i>{% endif %}
+        {% else %}
+          {% if not field.show_on_frontend %}<i class="fa fa-eye-slash" title="Esse campo é usado internamente e fica visível apenas no download completo"></i>{% endif %}
+        {% endif %}
+
+        {% if field.frontend_filter %}<i class="fa fa-filter" title="Você pode fazer filtros por esse campo na interface Web e na API"></i>{% endif %}
+
+        {% if field.searchable %}<i class="fa fa-search" title="Você pode utilizar a busca de texto completo nesse campo"></i>{% endif %}
+
+        {% if field.has_choices %}<i class="fa fa-list-ul" title="Esse campo possui valores categóricos"></i>{% endif %}
+
+        : {{ field.title }} </li>
+    {% endfor %}
+  </ul>
+  {% endif %}
+
+{% endfor %}

brasilio/urls.py

@@ -3,8 +3,11 @@
 from django.contrib import admin
 from django.urls import include, path
 
+from api.docs.views import dynamic_api_docs_view
+
 urlpatterns = [
     path("admin/", admin.site.urls),
+    path("api/docs/", dynamic_api_docs_view, name="api_docs"),
     path("api/", include("brasilio.api_urls")),
     path("auth/", include("brasilio_auth.urls", namespace="brasilio_auth")),
     path("covid19/", include("covid19.urls", namespace="covid19")),

core/templates/core/menu.html

@@ -32,6 +32,7 @@
   <li><a href="{% url 'core:dataset-list' %}">Datasets</a></li>
   <li><a href="{% url 'core:specials' %}">Páginas Especiais</a></li>
   <li><a href="{% url 'v1:api-root' %}">API</a></li>
+  <li><a href="{% url 'api_docs' %}">API Docs</a></li>
 </ul>
 
 <li><a class="dropdown-trigger" href="#!" data-target="{{id_prefix}}-about-dropdown">