Перейти до змісту

Умовний OpenAPI

🌐 Переклад ШІ та людьми

Цей переклад виконано ШІ під керівництвом людей. 🤝

Можливі помилки через неправильне розуміння початкового змісту або неприродні формулювання тощо. 🤖

Ви можете покращити цей переклад, допомігши нам краще спрямовувати AI LLM.

Англійська версія

Якщо потрібно, ви можете використовувати налаштування і змінні оточення, щоб умовно налаштовувати OpenAPI залежно від середовища, а також повністю вимикати його.

Про безпеку, API та документацію

Приховування інтерфейсів документації у продукційному середовищі не має бути способом захисту вашого API.

Це не додає жодної додаткової безпеки вашому API, операції шляху й надалі будуть доступні там, де вони є.

Якщо у вашому коді є вразливість, вона залишиться.

Приховування документації лише ускладнює розуміння того, як взаємодіяти з вашим API, і може ускладнити для вас його налагодження у продакшні. Це можна вважати просто формою Безпека через неясність.

Якщо ви хочете захистити ваш API, є кілька кращих дій, які ви можете зробити, наприклад:

  • Переконайтеся, що у вас добре визначені моделі Pydantic для тіл запитів і відповідей.
  • Налаштуйте потрібні дозволи та ролі за допомогою залежностей.
  • Ніколи не зберігайте паролі у відкритому вигляді, лише хеші паролів.
  • Реалізуйте та використовуйте відомі криптографічні інструменти, як-от pwdlib і токени JWT.
  • Додайте більш детальний контроль дозволів із областями OAuth2 там, де це потрібно.
  • ...тощо.

Втім, у вас може бути дуже специфічний випадок використання, коли справді потрібно вимкнути документацію API для певного середовища (наприклад, для продакшну) або залежно від конфігурацій зі змінних оточення.

Умовний OpenAPI з налаштувань і змінних оточення

Ви можете легко використати ті самі налаштування Pydantic, щоб налаштувати згенерований OpenAPI та інтерфейси документації.

Наприклад:

from fastapi import FastAPI
from pydantic_settings import BaseSettings


class Settings(BaseSettings):
    openapi_url: str = "/openapi.json"


settings = Settings()

app = FastAPI(openapi_url=settings.openapi_url)


@app.get("/")
def root():
    return {"message": "Hello World"}

Тут ми оголошуємо налаштування openapi_url з тим самим значенням за замовчуванням "/openapi.json".

Потім ми використовуємо його під час створення застосунку FastAPI.

Далі ви можете вимкнути OpenAPI (включно з інтерфейсами документації), встановивши змінну оточення OPENAPI_URL у пусту строку, наприклад:

$ OPENAPI_URL= uvicorn main:app

<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Потім, якщо ви перейдете за URL /openapi.json, /docs або /redoc, ви просто отримаєте помилку 404 Not Found на кшталт:

{
    "detail": "Not Found"
}