Python FastAPI 및 Swagger 활용한 API 설계 및 문서화

API를 생성하고 관리하는 데 도움이 되는 몇 가지 오픈 소스 도구가 있습니다. 먼저, Swagger 또는 OpenAPI Specification은 API 설계를 위한 표준으로 사용되며, 이를 통해 자동으로 API 문서를 생성할 수 있습니다.

Swagger/OpenAPI: API 설계 및 문서화를 위한 표준 스펙으로, 여러 언어 및 플랫폼에서 지원됩니다.

또한, API 요청 및 응답 스펙을 자동으로 생성하는 도구로는 다음이 있습니다.

Postman: API 개발 및 테스트 도구로, 요청 및 응답을 기반으로 스키마를 생성하여 문서화할 수 있습니다.
Insomnia: API 테스트 및 디자인을 위한 도구로, 자동으로 스키마를 생성하고 관리할 수 있습니다.

이러한 도구들을 조합하여 효과적으로 API를 만들고 관리할 수 있습니다.

java - Swagger Api Documentation in Spring API Gateway - Stack Overflow

내부 시스템에서 API를 생성하고 서비스하기 위해 다음 단계를 따를 수 있습니다.

API 설계 및 문서화
- Swagger 또는 OpenAPI 사용: API의 엔드포인트, 요청 및 응답 형식을 정의하는 Swagger 또는 OpenAPI Specification을 활용하여 API를 설계합니다.
- 문서화: Swagger UI 또는 ReDoc과 같은 도구를 사용하여 자동으로 생성된 API 문서를 확인하고 문서화합니다.
API 서버 구현
- 서버 프레임워크 선택: Flask 또는 Django (Python), Express (Node.js), Spring Boot (Java) 등과 같은 언어 및 프레임워크를 선택하여 API 서버를 구현합니다.
- API 엔드포인트 구현: Swagger 또는 OpenAPI 스펙을 기반으로 정의된 엔드포인트를 실제로 구현합니다.
보안 및 권한 관리
- 인증 및 권한 부여: API에 대한 안전한 접근을 위해 사용자를 인증하고 권한을 관리합니다. OAuth 또는 API 키를 활용할 수 있습니다.
데이터베이스 연동
- 데이터베이스 선택: API가 사용하는 데이터를 저장하기 위해 데이터베이스를 선택하고 연동합니다.
API 테스트
- 단위 및 통합 테스트: 구현한 API를 테스트하여 예상대로 작동하는지 확인합니다. Postman, Insomnia 등을 사용하여 수동 또는 자동으로 테스트할 수 있습니다.
API 배포
- 서버 환경 설정: API를 호스팅하기 위한 서버 환경을 구성합니다. AWS, Azure, Google Cloud 등의 클라우드 서비스를 고려할 수 있습니다.
- 배포: API 서버를 선택한 환경에 배포하고 필요에 따라 도메인 및 SSL 인증서를 설정합니다.
모니터링 및 유지 보수
- 로그 및 모니터링 설정: API의 활동을 추적하고 모니터링하기 위해 로그 및 모니터링 도구를 설정합니다.
- 보안 강화 및 업데이트: 보안 업데이트 및 새로운 기능 추가를 위해 정기적인 유지 보수를 수행합니다.

이러한 단계를 따르면 내부 시스템에서 API를 생성하고 서비스할 수 있습니다.

Redocly's Redoc와 Stoplight's Prism은 Web UI를 사용하여 API를 생성하고 관리할 수 있는 오픈 소스 도구 중 두 가지 예입니다. 이들은 Swagger 또는 OpenAPI Specification을 기반으로 동작하며, 사용자가 API를 시각적으로 설계하고 테스트할 수 있는 기능을 제공합니다.

1. Redocly's Redoc

도구 설치: npm을 사용하여 Redoc 설치
```
npm install -g redoc-cli
```
API 설계 및 문서 작성
- Swagger 또는 OpenAPI Specification을 사용하여 API 설계 및 문서 작성. 예를 들어, openapi.yaml 파일 생성.
Redoc 실행
```
redoc-cli serve openapi.yaml
```
위 명령어를 실행하면 브라우저에서 API 문서가 열립니다.

2. Stoplight's Prism

도구 설치: Docker를 사용하여 Prism 설치
```
docker pull stoplight/prism:4
```
API 설계 및 문서 작성
- Swagger 또는 OpenAPI Specification을 사용하여 API 설계 및 문서 작성.
Prism 실행
```
docker run -v $(pwd):/tmp -it stoplight/prism:4 mock -d /tmp/openapi.yaml
```
위 명령어를 실행하면 Prism이 모의 API를 제공합니다.

이러한 도구들을 사용하면 Web UI에서 API를 시각적으로 설계하고 테스트할 수 있습니다. 앞의 단계에서 생성한 API 문서는 사용자가 요청 및 응답을 확인하고 테스트할 수 있는 Web UI를 통해 쉽게 접근할 수 있게 됩니다.

Automatically generate RESTful API documentation in GoLang by Santosh Shrestha

Web UI에서 API를 시각적으로 설계하고, 해당 API를 /api/abc와 같은 형태로 호출할 수 있도록 자동으로 구성하는 프로세스를 간단히 설명하겠습니다.

1. Redocly's Redoc를 이용한 예시

API 설계 및 문서 작성
- Redoc Web UI를 사용하여 API를 시각적으로 설계하고, Swagger 또는 OpenAPI Specification을 생성합니다.

API 서버 구현

선택한 언어 및 프레임워크를 사용하여 API 서버를 구현합니다. 예를 들어, Express (Node.js)를 사용하면 다음과 같이 라우팅을 설정할 수 있습니다.

const express = require('express');
const app = express();

// Your API routes
app.use('/api', require('./your_api_routes'));

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
 console.log(`Server is running on port ${PORT}`);
});

API 라우팅 구현

your_api_routes.js 파일에는 Redoc에서 정의한 API 스펙에 따라 라우팅을 구현합니다.

const express = require('express');
const router = express.Router();

// Example route
router.get('/abc', (req, res) => {
 // Your API logic here
 res.json({ message: 'Hello from /api/abc' });
});

module.exports = router;

Redoc 실행 및 API 호출
- Redoc로 생성된 문서를 확인하고, /api/abc와 같은 엔드포인트를 호출하여 작동 여부를 확인합니다.

2. Stoplight's Prism를 이용한 예시

API 설계 및 문서 작성
- Stoplight Studio Web UI를 사용하여 API를 설계하고, Swagger 또는 OpenAPI Specification을 생성합니다.
API 모의 서버 실행
- Docker를 사용하여 Prism 모의 서버를 실행합니다.
```
docker run -v $(pwd):/tmp -it stoplight/prism:4 mock -d /tmp/openapi.yaml
```
API 호출
- /api/abc와 같은 형태로 생성된 API를 호출하여 모의 서버의 응답을 확인합니다.

이러한 프로세스를 따르면 Web UI에서 생성한 API를 특정 엔드포인트로 호출하여 작동 여부를 확인할 수 있습니다. 필요한 경우 API 서버를 배포하고 외부에서도 접근 가능하도록 설정할 수 있습니다.

IP 주소를 기반으로 국가 정보를 제공하는 API를 만들고 서비스하는 과정은 다음과 같습니다. 이 예제에서는 Node.js와 Express를 사용합니다.

1. IP 기반 국가 정보 제공을 위한 API 생성

Express 및 관련 라이브러리 설치

npm init -y
npm install express ip-api-wrapper

Express 앱 설정 (app.js)

const express = require('express');
const ipApiWrapper = require('ip-api-wrapper');
const app = express();
const PORT = process.env.PORT || 3000;

// Middleware to extract IP from request
app.use((req, res, next) => {
  req.clientIp = req.headers['x-forwarded-for'] || req.connection.remoteAddress;
  next();
});

// API endpoint to get country by IP
app.get('/api/getip', async (req, res) => {
  try {
    const ipInfo = await ipApiWrapper.lookup(req.clientIp);
    res.json({ country: ipInfo.country });
  } catch (error) {
    console.error('Error:', error);
    res.status(500).json({ error: 'Internal Server Error' });
  }
});

app.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
});

IP 정보를 가져오기 위한 라이브러리 설정 (ip-api-wrapper.js)

const axios = require('axios');

async function lookup(ip) {
  const response = await axios.get(`http://ip-api.com/json/${ip}`);
  return response.data;
}

module.exports = {
  lookup,
};

2. 서비스 구동

Express 앱 실행
```
node app.js
```
API 테스트
- 브라우저나 API 클라이언트를 통해 /api/getip 엔드포인트로 요청을 보내어 결과를 확인합니다.
- 예를 들어, 브라우저에서 http://localhost:3000/api/getip로 접속하면 IP에 대한 국가 정보가 반환됩니다.

3. 서비스 배포 (옵션)

Heroku 등의 클라우드 서비스에 배포
- Heroku에 계정을 만들고 Heroku CLI를 설치한 후, 다음 명령어를 통해 배포할 수 있습니다.
```
heroku create
git push heroku master
```
API 테스트 (배포 후)
- 배포된 앱의 URL을 통해 /api/getip 엔드포인트로 요청을 보내어 결과를 확인합니다.

이러한 단계를 따르면 IP 주소를 기반으로 국가 정보를 제공하는 간단한 API를 만들고 서비스할 수 있습니다.

아래는 /api/getip와 함께 /api/domain 엔드포인트를 추가하여 도메인 정보를 반환하는 API의 코드입니다. 이 예제에서는 whois-json 라이브러리를 사용하여 간단한 도메인 정보를 가져옵니다.

1. Express 앱 설정 (`app.js`)

const express = require('express');
const ipApiWrapper = require('ip-api-wrapper');
const whois = require('whois-json');
const app = express();
const PORT = process.env.PORT || 3000;

app.use((req, res, next) => {
  req.clientIp = req.headers['x-forwarded-for'] || req.connection.remoteAddress;
  next();
});

// API endpoint to get country by IP
app.get('/api/getip', async (req, res) => {
  try {
    const ipInfo = await ipApiWrapper.lookup(req.clientIp);
    res.json({ country: ipInfo.country });
  } catch (error) {
    console.error('Error:', error);
    res.status(500).json({ error: 'Internal Server Error' });
  }
});

// API endpoint to get domain info
app.get('/api/domain', async (req, res) => {
  const domain = req.query.domain;

  if (!domain) {
    return res.status(400).json({ error: 'Missing domain parameter' });
  }

  try {
    const domainInfo = await whois(domain);
    res.json({ domainInfo });
  } catch (error) {
    console.error('Error:', error);
    res.status(500).json({ error: 'Internal Server Error' });
  }
});

app.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
});

2. Express 앱 실행

node app.js

이제 /api/domain?domain=example.com와 같은 형태로 도메인을 파라미터로 받아 정보를 반환하는 API를 사용할 수 있습니다. 요청을 보내어 결과를 확인해보세요.

API의 모든 스펙을 표시하는 엔드포인트를 생성하기 위해 Express 앱을 확장하겠습니다. 이를 위해 express-openapi-validator 라이브러리를 사용하여 Swagger 또는 OpenAPI Specification을 활용하겠습니다.

1. Express 앱 설정 (`app.js`)

const express = require('express');
const ipApiWrapper = require('ip-api-wrapper');
const whois = require('whois-json');
const { OpenApiValidator } = require('express-openapi-validator');
const app = express();
const PORT = process.env.PORT || 3000;

app.use((req, res, next) => {
  req.clientIp = req.headers['x-forwarded-for'] || req.connection.remoteAddress;
  next();
});

// API endpoint to get country by IP
app.get('/api/getip', async (req, res) => {
  try {
    const ipInfo = await ipApiWrapper.lookup(req.clientIp);
    res.json({ country: ipInfo.country });
  } catch (error) {
    console.error('Error:', error);
    res.status(500).json({ error: 'Internal Server Error' });
  }
});

// API endpoint to get domain info
app.get('/api/domain', async (req, res) => {
  const domain = req.query.domain;

  if (!domain) {
    return res.status(400).json({ error: 'Missing domain parameter' });
  }

  try {
    const domainInfo = await whois(domain);
    res.json({ domainInfo });
  } catch (error) {
    console.error('Error:', error);
    res.status(500).json({ error: 'Internal Server Error' });
  }
});

// Express OpenAPI Validator setup
new OpenApiValidator({
  apiSpec: './openapi.yaml',
  validateResponses: true, // validate responses
}).install(app);

app.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
});

2. API 스펙 정의 (`openapi.yaml`)

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /api/getip:
    get:
      summary: Get country by IP
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              example: { country: 'US' }
  /api/domain:
    get:
      summary: Get domain info
      parameters:
        - name: domain
          in: query
          required: true
          description: Domain to look up
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              example: { domainInfo: { /* your domain info structure */ } }

3. Express 앱 실행

node app.js

이제 /api 엔드포인트를 통해 API 스펙을 확인할 수 있습니다. 브라우저 또는 API 클라이언트를 사용하여 해당 엔드포인트에 요청을 보내어 API 스펙을 확인해보세요.

Build an Event-Driven Architecture with FastAPI and Redis Pub/Sub & Deploy it in Kubernetes

The Ultimate FastAPI Tutorial Part 12 - Setting Up a React Frontend

Python 기반에서 API를 만들고 관리하기 위한 여러 도구와 프레임워크가 있습니다. 그 중에서도 FastAPI는 최근에 빠르게 인기를 얻고 있는 높은 성능의 모던한 웹 프레임워크 중 하나입니다.

FastAPI를 사용한 간단한 API 예제

FastAPI 설치
```
pip install fastapi uvicorn
```

FastAPI 앱 코드 작성 (main.py)

from fastapi import FastAPI

app = FastAPI()

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

@app.get("/items/{item_id}")
def read_item(item_id: int, query_param: str = None):
    return {"item_id": item_id, "query_param": query_param}

FastAPI 앱 실행
```
uvicorn main:app --reload
```
이렇게 하면 FastAPI 앱이 개발 서버에서 실행됩니다.
API 테스트
- 브라우저 또는 API 클라이언트를 사용하여 http://127.0.0.1:8000에 접속하여 API 엔드포인트를 테스트합니다.

FastAPI는 Python 3.7 이상에서 asyncio 및 Pydantic을 활용하여 높은 성능의 API를 빠르게 구축할 수 있도록 지원합니다. Swagger 및 ReDoc과 같은 자동 문서화 도구를 포함하여 개발자 경험을 향상시키기 위한 다양한 기능을 제공합니다.

이 외에도 Flask, Django REST framework 등이 있으며, 프로젝트의 특정 요구사항에 따라 선택할 수 있습니다. FastAPI는 특히 타입 힌트와 Pydantic을 활용한 데이터 유효성 검사, 자동 문서 생성 등의 특징으로 인해 많은 개발자들 사이에서 인기를 얻고 있습니다.

728x90

저작자표시 비영리 동일조건

pages.kr 날으는물고기 <º))))><

Python FastAPI 및 Swagger 활용한 API 설계 및 문서화

Python FastAPI 및 Swagger 활용한 API 설계 및 문서화

1. Redocly's Redoc

2. Stoplight's Prism

1. Redocly's Redoc를 이용한 예시

2. Stoplight's Prism를 이용한 예시

1. IP 기반 국가 정보 제공을 위한 API 생성

2. 서비스 구동

3. 서비스 배포 (옵션)

1. Express 앱 설정 (`app.js`)

2. Express 앱 실행

1. Express 앱 설정 (`app.js`)

2. API 스펙 정의 (`openapi.yaml`)

3. Express 앱 실행

FastAPI를 사용한 간단한 API 예제

댓글

티스토리툴바

Python FastAPI 및 Swagger 활용한 API 설계 및 문서화

Python FastAPI 및 Swagger 활용한 API 설계 및 문서화

1. Redocly's Redoc

2. Stoplight's Prism

1. Redocly's Redoc를 이용한 예시

2. Stoplight's Prism를 이용한 예시

1. IP 기반 국가 정보 제공을 위한 API 생성

2. 서비스 구동

3. 서비스 배포 (옵션)

1. Express 앱 설정 (app.js)

2. Express 앱 실행

1. Express 앱 설정 (app.js)

2. API 스펙 정의 (openapi.yaml)

3. Express 앱 실행

FastAPI를 사용한 간단한 API 예제

관련글

댓글

티스토리툴바

1. Express 앱 설정 (`app.js`)

1. Express 앱 설정 (`app.js`)

2. API 스펙 정의 (`openapi.yaml`)