### [Swagger](https://swagger.io/) / [OpenAPI](https://github.com/OAI/OpenAPI-Specification/) { #swagger-openapi }

제가 Django REST Framework에서 가장 원했던 주요 기능은 자동 API 문서화였습니다.

그 후 JSON(또는 JSON의 확장인 YAML)을 사용해 API를 문서화하는 표준인 Swagger가 있다는 것을 알게 되었습니다.

그리고 Swagger API를 위한 웹 사용자 인터페이스도 이미 만들어져 있었습니다. 그래서 API에 대한 Swagger 문서를 생성할 수 있다면, 이 웹 사용자 인터페이스를 자동으로 사용할 수 있게 됩니다.

어느 시점에 Swagger는 Linux Foundation으로 넘어가 OpenAPI로 이름이 바뀌었습니다.

**FastAPI** 애플리케이션에서 다양한 메타데이터 구성을 사용자 맞춤 설정할 수 있습니다.

## API에 대한 메타데이터 { #metadata-for-api }

OpenAPI 명세 및 자동화된 API 문서 UI에 사용되는 다음 필드를 설정할 수 있습니다:

| 매개변수 | 타입 | 설명 |
|----------|------|-------|
| `title` | `str` | API의 제목입니다. |
| `summary` | `str` | API에 대한 짧은 요약입니다. <small>OpenAPI 3.1.0, FastAPI 0.99.0부터 사용 가능.</small> |
| `description` | `str` | API에 대한 짧은 설명입니다. 마크다운을 사용할 수 있습니다. |

# 요청 본문 { #request-body }

클라이언트(브라우저라고 해봅시다)로부터 여러분의 API로 데이터를 보내야 할 때, **요청 본문**으로 보냅니다.

**요청** 본문은 클라이언트에서 API로 보내지는 데이터입니다. **응답** 본문은 API가 클라이언트로 보내는 데이터입니다.

여러분의 API는 대부분의 경우 **응답** 본문을 보내야 합니다. 하지만 클라이언트는 항상 **요청 본문**을 보낼 필요는 없고, 때로는 (쿼리 매개변수와 함께) 어떤 경로만 요청하고 본문은 보내지 않을 수도 있습니다.

**요청** 본문을 선언하기 위해서 모든 강력함과 이점을 갖춘 [Pydantic](https://docs.pydantic.dev/) 모델을 사용합니다.

/// info | 정보

# ADR-0003 - Avoid introducing Groovy types to public API

## Status

- ACCEPTED on 2024-01-12

## Context

Gradle's public API requires equal access from all JVM-based languages.
Kotlin, Groovy, Java, and other JVM-based languages should be able to use the Gradle API without relying on another language's standard library.

Historically, Gradle has shipped with some Groovy types in very prominent APIs.

# ADR-0006 - Use of Provider APIs in Gradle

## Status

- ACCEPTED on 2024-06-21

## Context

	// Generate string error response.
	writeResponse(w, err.HTTPStatusCode, []byte(err.Description), mimeNone)
}

// writeErrorResponseJSON - writes error response in JSON format;
// useful for admin APIs.
func writeErrorResponseJSON(ctx context.Context, w http.ResponseWriter, err APIError, reqURL *url.URL) {
	// Generate error response.

```

`fastapi dev` 서버는 자동으로 리로딩되어야 합니다.

### 대화형 API 문서 업그레이드 { #interactive-api-docs-upgrade }

이제 [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)로 이동합니다.

* 대화형 API 문서는 새 본문을 포함해 자동으로 업데이트됩니다:

![Swagger UI](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png)

* "Try it out" 버튼을 클릭하면, 매개변수를 채우고 API와 직접 상호작용할 수 있습니다:

/// tip | 팁

여기서 `tokenUrl="token"`은 아직 만들지 않은 상대 URL `token`을 가리킵니다. 상대 URL이므로 `./token`과 동일합니다.

상대 URL을 사용하므로, 예를 들어 API가 `https://example.com/`에 있다면 `https://example.com/token`을 가리킵니다. 하지만 API가 `https://example.com/api/v1/`에 있다면 `https://example.com/api/v1/token`을 가리킵니다.

상대 URL을 사용하는 것은 [프록시 뒤에서](../../advanced/behind-a-proxy.md) 같은 고급 사용 사례에서도 애플리케이션이 계속 동작하도록 보장하는 데 중요합니다.

///

Yuri Schimke <******@****.***> 1690028931 +0100

- 애플리케이션이 로컬(예: `localhost`) 또는 내부 네트워크에서 실행 중이고
- 애플리케이션에 인증이 없어 같은 네트워크에서 오는 모든 요청을 신뢰한다고 가정하는 경우

## 공격 예시 { #example-attack }

로컬 AI 에이전트를 실행하는 방법을 만들었다고 가정해 봅시다.

이 에이전트는 다음 위치에 API를 제공합니다:

```
http://localhost:8000/v1/agents/multivac
```

또한 다음 위치에 프론트엔드가 있습니다:

```
http://localhost:8000
```

/// tip | 팁

두 주소 모두 같은 호스트를 사용합니다.

///