Debug & Think

[Server] ASP.NET Core Web API 기초| 웹서버 만들기 & Swagger로 API 테스트 본문

카테고리 없음

[Server] ASP.NET Core Web API 기초| 웹서버 만들기 & Swagger로 API 테스트

J.Note 2025. 7. 6. 17:15

ASP.NET Core Web API로 RESTful 웹서버를 처음부터 구축하는 방법을 자세히 안내합니다.

Visual Studio 설정부터 Swagger를 활용한 API 테스트까지 적었습니다.

 

서버 개발을 처음 접하는 분들을 위해, ASP.NET Core Web API를 사용하여

웹서버를 구축하고 실행해보는 전체 과정을 정리했습니다.

  • 강의 기반으로 배운 내용을 재정리
  • Web Server와 Game Server의 개념 비교
  • Swagger, Controller, Route 설정 등 핵심 개념 설명
  • 실습 코드 및 구조를 쉽게 설명

🧠 서버란?

서버는 사실 하나의 컴퓨터입니다. 단지, 다른 컴퓨터의 요청을 상시로 받을 수 있도록 대기 상태로 있는 프로그램일 뿐입니다.

🟦 Web Server VS Game Server

구분 Web Server Game Server
예시 테이크아웃 식당 일반 식당
요청 손님이 와서 음식 받고 끝 손님과 지속 상호작용
상태 기억 기억 안함 (Stateless) 기억함 (Stateful)
트래픽 특성 간헐적 요청 지속적, 실시간 요청
활용 예 REST API, 홈페이지 MMO 게임, 실시간 통신

 

📝 Web Server는 상태를 기억하지 않고 요청과 응답이 단발성인 구조입니다.

반면, Game Server는 실시간 상호작용이 필수이며, 클라이언트의 상태를 계속 유지합니다.

 

 

🚧 서버 개발의 방향 잡기

서버라고 해도 모든 걸 처음부터 만드는 경우는 거의 없습니다. 대개 프레임워크를 이용하여 빠르게 개발합니다.

언어 프레임워크 예시
C# ASP.NET Core
Java Spring Boot
JS Node.js
Python Django, Flask

이 글에서는 C# 기반의 ASP.NET Core Web API를 사용하여 RESTful 서버를 구성해 봅니다.


 

🛠️ 1단계: ASP.NET Core Web API 설치 및 프로젝트 생성

1. Visual Studio Instalelr 워크로드 목록에서 필요 항복 설치 확인

 

 

 

2. ASP 검색 -> ASP.NET Core Web API 설치


3. 경로 설정 및 기본 설정대로 진행

 


🔄 2단계: HTTPS → HTTP 변경 (테스트용)

기본 설정은 HTTPS. 학습 및 실습 환경에서는 HTTP가 편리하기에 변경

  • launchSettings.json에서 applicationUrl 값을 http://localhost:포트로 수정

 

  • 개발 시 HTTPS 인증서 경고는 무시(예(Y)) 가능하지만, 실제 서비스에서는 절대 무시하면 안 됩니다.


🌐 3단계: Swagger를 통한 API 테스트

Swagger? API 문서를 자동으로 생성해주며, 직접 테스트할 수 있는 인터페이스도 제공합니다.

  • 브라우저에서 실행 시 Swagger UI 페이지 확인 가능
  • 각 API를 클릭하고 Try it out 버튼으로 직접 요청 가능
  • 요청 결과는 JSON으로 반환

Swagger는 클라이언트 없이도 서버의 응답을 확인할 수 있는 훌륭한 도구입니다.

 

 

HTTP로 변경후 실행 실행하면 아래와 같이 Swagger 사이트와 터미널 창이 뜸

클라이언트 역할하는 Wep / 서버 실행되고 있는 상태

 

 

Try it out 누르면 테스트로 적용된 WeatherForest를 요청한 정보를 json으로 보내는 것을 확인 가능

 

 

 

🔹어떻게 Swagger에서 확인이 가능할까?

Program에서 확인해보면 Swagger추가되는 함수가 있습니다.

 

이 모든 함수를 완벽하게 이해하려고 하지 말고,

프레임워크가 어떤식으로 흐름이 이어지고 작업되는지 이해하는게 중요합니다.

 


🧩 4단계: 컨트롤러 및 라우팅 구조 이해

기본적으로 Controller는 클라이언트 요청을 처리하는 클래스입니다.

[ApiController]
[Route("weather")]
public class WeatherForecastController : ControllerBase
{
    [HttpGet]
    public IEnumerable<WeatherForecast> Get() { ... }
}
  • [Route("weather")]는 경로를 지정합니다. /weather로 요청 시 이 컨트롤러가 실행됨
  • ControllerBase는 Web API 전용 컨트롤러입니다 (View 렌더링 X)

🧪 5단계: 테스트용 Controller 작성

컨트롤러(Controller) 추가방법

1. 추가 -> 컨트롤러 선택

 

2. 읽기/쓰기 포함된 MVC 컨트롤러

 

3. 읽기/쓰기 포함된 MVC 컨트롤러

 

❗ Controller vs ControllerBase

첫 Controller 생성이후 강의와 내 코드와 다른점이 있었습니다.

public class TestController : Controller

    [HttpPost]
    public void Post(IFormCollection collection) { }
}
public class TestController : ControllerBase

    [HttpPost]
    public void Post( [FromBody] string value ) { }
}
Controller는 ControllerBase를 상속 ControllerBase는 Web API 전용으로 설계
View 렌더링 등 MVC 기능 O View 렌더링 등 MVC 기능 X
Web API라면 ControllerBase를 상속하는 것이 권장됩니다.

 

프로젝트를 진행하면서 저는 유니티 기반 Web통신을 할 예정이기에 ControllerBase로 활용했습니다.

 

Controller class

[ApiController]
[Route("test")]
public class TestController : ControllerBase
{
    [HttpPost]
    public void Post([FromBody] string value)
    {
        Console.WriteLine(value);
    }
}
  • FromBody: 요청 Body에서 데이터를 추출하여 매핑합니다 (주로 JSON)
  • Post: POST 방식으로 데이터를 받습니다.

 

✅ REST 메서드 정리

구분 설명 예시
GET 서버에서 데이터를 조회할 때 사용 사용자 목록 보기, 게시글 읽기 등
POST 서버에 데이터를 생성/전송할 때 사용 회원가입, 게시글 작성 등
PUT 서버에 존재하는 데이터를 전체 수정 또는 새로 생성할 때 사용 회원 정보 수정 등
DELETE 서버에서 특정 데이터를 삭제할 때 사용 게시글 삭제 등
PATCH 서버의 리소스 일부를 수정할 때 사용 게시글 제목만 수정, 일부 필드 변경 등

 

 


📦 6단계: 요청 데이터 클래스 설계

사용될 데이터 양식에 맞게 class를  만들어 둡니다.

[HttpPost]
public TestPackRes TestPost([FromBody] TestPackReq value)
{
    TestPackRes result = new TestPackRes();
    result.success = true;
    return result;

}
  • JSON 구조에 맞는 클래스 설계 필요
  • 복잡한 데이터 구조일수록 클래스 분리 권장

🧭 7단계: 추가 라우팅 구성

여러개로 분리하려고 한다면 내부에서 추가 Route 설정할 수 있습니다.

[Route("user/login")]
[HttpPost]
public IActionResult Login([FromBody] LoginRequest request) { ... }
    • Route 속성을 다양하게 지정하여 구조적 RESTful API 구성 가능
    • Swagger에서도 경로 자동 반영

 

 

 

 

다시 서버 실행하면 swagger에 변경된 걸 확인할 수 있습니다.

 

 

 

 


📚 용어 정리

용어 설명
REST
(Representational State Transfer) 
이론적 개념 및 아키텍처 스타일(자원을 URI로 표현하고 HTTP 메서드로 조작하는 방식)
RESTful API REST의 원칙을 실제로 구현한 웹 서비스나 API를 설명 
URI
(Uniform Resource Identifier)
고유하게 식별되는 대상
Controller 클라이언트 요청을 처리하는 클래스
Swagger API 문서 자동화 + 테스트 도구
FromBody HTTP Body의 데이터를 매핑하는 데 사용
HTTP vs HTTPS HTTPS는 암호화된 HTTP

 


 

🚀 마무리

  • Web 서버는 '요청 - 응답' 중심의 구조로 작동
  • 처음에는 모든 구조를 완벽히 이해하기보다 "흐름을 파악"하는 것이 중요
  • 테스트를 통해 확장해나가면서 자연스럽게 익힐 수 있다.

 

웹서버를 처음 만드는 과정을 캡처와 예시 코드로 직접 따라하며, 서버의 기본 구조와 흐름을 익힐 수 있었습니다.