S02L01 – ์Šคํ”„๋ง ๋ถ€ํŠธ REST API, JWT ๋ฐ๋ชจ

html

Spring Boot RESTful API์—์„œ Swagger์™€ JWT ํ†ตํ•ฉ: ์ข…ํ•ฉ ๊ฐ€์ด๋“œ


๋ชฉ์ฐจ

  1. ์†Œ๊ฐœ
  2. Swagger ์ดํ•ดํ•˜๊ธฐ
  3. JWT (JSON Web Tokens) ์†Œ๊ฐœ
  4. Spring Boot์—์„œ Swagger ์„ค์ •ํ•˜๊ธฐ
  5. JWT ์ธ์ฆ ๊ตฌํ˜„
  6. Swagger UI ์‚ฌ์šฉ์ž ์ง€์ •
  7. Swagger๋กœ API ํ…Œ์ŠคํŠธํ•˜๊ธฐ
  8. ๋ชจ๋ฒ” ์‚ฌ๋ก€ ๋ฐ ๋ณด์•ˆ ๊ณ ๋ ค ์‚ฌํ•ญ
  9. ๊ฒฐ๋ก 

์†Œ๊ฐœ

ํ˜„๋Œ€ ์›น ๊ฐœ๋ฐœ ๋ถ„์•ผ์—์„œ ์•ˆ์ „ํ•˜๊ณ  ์ž˜ ๋ฌธ์„œํ™”๋œ API๋ฅผ ๋งŒ๋“œ๋Š” ๊ฒƒ์€ ๋งค์šฐ ์ค‘์š”ํ•ฉ๋‹ˆ๋‹ค. ์ด ์ „์ž์ฑ…์€ Swagger์™€ JWT (JSON Web Tokens)๋ฅผ Spring Boot RESTful API์— ํ†ตํ•ฉํ•˜๋Š” ๋ฐฉ๋ฒ•์„ ์ž์„ธํžˆ ๋‹ค๋ฃน๋‹ˆ๋‹ค. API ๋ฌธ์„œํ™”๋ฅผ ์œ„ํ•ด Swagger๋ฅผ ํ™œ์šฉํ•˜๊ณ  ์ธ์ฆ์„ ์œ„ํ•ด JWT๋ฅผ ์‚ฌ์šฉํ•จ์œผ๋กœ์จ, ๊ฐœ๋ฐœ์ž๋“ค์€ ๊ฒฌ๊ณ ํ•˜๊ณ  ์•ˆ์ „ํ•˜๋ฉฐ ์œ ์ง€ ๊ด€๋ฆฌ๊ฐ€ ์šฉ์ดํ•œ ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜์„ ๊ตฌ์ถ•ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์ด ๊ฐ€์ด๋“œ๋Š” ์ดˆ๋ณด์ž์™€ ๊ธฐ๋ณธ ์ง€์‹์„ ๊ฐ€์ง„ ๊ฐœ๋ฐœ์ž๋ฅผ ์œ„ํ•ด ๋งž์ถคํ™”๋˜์–ด ์žˆ์œผ๋ฉฐ, ๋ช…ํ™•ํ•˜๊ณ  ๊ฐ„๊ฒฐํ•œ ์ง€์นจ๊ณผ ์‹ค์šฉ์ ์ธ ์˜ˆ์ œ๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค.


Swagger ์ดํ•ดํ•˜๊ธฐ

Swagger๋ž€ ๋ฌด์—‡์ธ๊ฐ€?

Swagger๋Š” RESTful ์›น ์„œ๋น„์Šค๋ฅผ ์„ค๊ณ„, ๊ตฌ์ถ•, ๋ฌธ์„œํ™” ๋ฐ ์†Œ๋น„ํ•˜๋Š” ๋ฐ ๋„์›€์„ ์ฃผ๋Š” ์˜คํ”ˆ ์†Œ์Šค ํ”„๋ ˆ์ž„์›Œํฌ์ž…๋‹ˆ๋‹ค. ๊ตฌํ˜„ ๋กœ์ง ์—†์ด API์˜ ๋ฆฌ์†Œ์Šค๋ฅผ ์‹œ๊ฐํ™”ํ•˜๊ณ  ์ƒํ˜ธ ์ž‘์šฉํ•  ์ˆ˜ ์žˆ๋Š” ์‚ฌ์šฉ์ž ์นœํ™”์ ์ธ ์ธํ„ฐํŽ˜์ด์Šค๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค.

Swagger์˜ ์ฃผ์š” ๊ธฐ๋Šฅ

  • API ๋ฌธ์„œํ™”: ์ž๋™์œผ๋กœ ๋Œ€ํ™”ํ˜• ๋ฌธ์„œ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค.
  • API ํ…Œ์ŠคํŠธ: UI์—์„œ ์ง์ ‘ ์—”๋“œํฌ์ธํŠธ๋ฅผ ํ…Œ์ŠคํŠธํ•  ์ˆ˜ ์žˆ๋„๋ก ๋„์™€์ค๋‹ˆ๋‹ค.
  • ์Šคํ‚ค๋งˆ ์ •์˜: ์š”์ฒญ ๋ฐ ์‘๋‹ต์„ ์œ„ํ•œ ๋ฐ์ดํ„ฐ ๋ชจ๋ธ๊ณผ ๊ตฌ์กฐ๋ฅผ ์ •์˜ํ•ฉ๋‹ˆ๋‹ค.

API ๊ฐœ๋ฐœ์—์„œ Swagger์˜ ์ค‘์š”์„ฑ

Swagger๋Š” ๋ช…ํ™•ํ•œ ๋ฌธ์„œ๋ฅผ ์ œ๊ณตํ•˜์—ฌ ํ˜‘์—…๊ณผ ์œ ์ง€ ๊ด€๋ฆฌ๋ฅผ ์šฉ์ดํ•˜๊ฒŒ ํ•จ์œผ๋กœ์จ ๊ฐœ๋ฐœ ์›Œํฌํ”Œ๋กœ์šฐ๋ฅผ ํ–ฅ์ƒ์‹œํ‚ต๋‹ˆ๋‹ค. API ์—”๋“œํฌ์ธํŠธ์™€ ๊ทธ ๊ธฐ๋Šฅ์„ ์ดํ•ดํ•˜๋Š” ๊ณผ์ •์„ ๋‹จ์ˆœํ™”ํ•ฉ๋‹ˆ๋‹ค.


JWT (JSON Web Tokens) ์†Œ๊ฐœ

JWT๋ž€ ๋ฌด์—‡์ธ๊ฐ€?

JWT (JSON Web Token)์€ ๋‘ ๋‹น์‚ฌ์ž ๊ฐ„์— ์ „์†ก๋  ํด๋ ˆ์ž„์„ ํ‘œํ˜„ํ•˜๋Š” ์ปดํŒฉํŠธํ•˜๊ณ  URL-์•ˆ์ „ํ•œ ์ˆ˜๋‹จ์ž…๋‹ˆ๋‹ค. ์›น ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜์—์„œ ์ธ์ฆ ๋ฐ ๊ถŒํ•œ ๋ถ€์—ฌ์— ๋„๋ฆฌ ์‚ฌ์šฉ๋ฉ๋‹ˆ๋‹ค.

JWT์˜ ์ฃผ์š” ๊ตฌ์„ฑ ์š”์†Œ

  1. ํ—ค๋”: ํ† ํฐ์˜ ์œ ํ˜•๊ณผ ์„œ๋ช… ์•Œ๊ณ ๋ฆฌ์ฆ˜์„ ํฌํ•จํ•˜๋Š” ๋ฉ”ํƒ€๋ฐ์ดํ„ฐ๋ฅผ ๋‹ด๊ณ  ์žˆ์Šต๋‹ˆ๋‹ค.
  2. ํŽ˜์ด๋กœ๋“œ: ์‚ฌ์šฉ์ž ๋˜๋Š” ์—”ํ‹ฐํ‹ฐ์— ๋Œ€ํ•œ ํด๋ ˆ์ž„ ๋˜๋Š” ์ง„์ˆ ์„ ๋‹ด๊ณ  ์žˆ์Šต๋‹ˆ๋‹ค.
  3. ์„œ๋ช…: ํ† ํฐ์ด ๋ณ€๊ฒฝ๋˜์ง€ ์•Š์•˜์Œ์„ ๊ฒ€์ฆํ•˜์—ฌ ํ† ํฐ์˜ ๋ฌด๊ฒฐ์„ฑ์„ ๋ณด์žฅํ•ฉ๋‹ˆ๋‹ค.

JWT ์‚ฌ์šฉ์˜ ์žฅ์ 

  • ๋ฌด์ƒํƒœ ์ธ์ฆ: ์„œ๋ฒ„ ์ธก ์„ธ์…˜์˜ ํ•„์š”์„ฑ์„ ์—†์•ฑ๋‹ˆ๋‹ค.
  • ํ™•์žฅ์„ฑ: ๋ถ„์‚ฐ ์‹œ์Šคํ…œ ๋ฐ ๋งˆ์ดํฌ๋กœ์„œ๋น„์Šค์— ์ ํ•ฉํ•ฉ๋‹ˆ๋‹ค.
  • ๋ณด์•ˆ: ๋งŒ๋ฃŒ ์‹œ๊ฐ„์ด ์žˆ๋Š” ์‚ฌ์šฉ์ž ์ •๋ณด๋ฅผ ์•ˆ์ „ํ•˜๊ฒŒ ์ธ์ฝ”๋”ฉํ•ฉ๋‹ˆ๋‹ค.

Spring Boot์—์„œ Swagger ์„ค์ •ํ•˜๊ธฐ

ํ•„์ˆ˜ ์กฐ๊ฑด

  • Spring Boot์— ๋Œ€ํ•œ ๊ธฐ๋ณธ ์ง€์‹.
  • Java Development Kit (JDK) ์„ค์น˜.
  • Maven ๋˜๋Š” Gradle ๋นŒ๋“œ ๋„๊ตฌ.

๋‹จ๊ณ„๋ณ„ ํ†ตํ•ฉ

  1. Swagger ์˜์กด์„ฑ ์ถ”๊ฐ€

  • Swagger ์„ค์ •
  • Swagger UI ์ ‘๊ทผ
  • Spring Boot ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜์„ ์‹œ์ž‘ํ•˜๊ณ  http://localhost:8080/swagger-ui/๋กœ ์ด๋™ํ•˜์—ฌ ๋Œ€ํ™”ํ˜• API ๋ฌธ์„œ๋ฅผ ํ™•์ธํ•˜์‹ญ์‹œ์˜ค.


    JWT ์ธ์ฆ ๊ตฌํ˜„

    ์™œ JWT๋ฅผ ์‚ฌ์šฉํ•˜๋Š”๊ฐ€?

    JWT๋Š” ๋ฌด์ƒํƒœ ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜์—์„œ ์ธ์ฆ ๋ฐ ๊ถŒํ•œ ๋ถ€์—ฌ๋ฅผ ์ฒ˜๋ฆฌํ•˜๋Š” ์•ˆ์ „ํ•˜๊ณ  ํšจ์œจ์ ์ธ ๋ฐฉ๋ฒ•์„ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. ์„œ๋ฒ„ ์ธก ์„ธ์…˜์„ ์œ ์ง€ํ•˜์ง€ ์•Š๊ณ  ๊ฐ ์š”์ฒญ์ด ์ธ์ฆ๋˜๋„๋ก ๋ณด์žฅํ•ฉ๋‹ˆ๋‹ค.

    Spring Boot์—์„œ JWT ์„ค์ •

    1. JWT ์˜์กด์„ฑ ์ถ”๊ฐ€

  • JWT ์œ ํ‹ธ๋ฆฌํ‹ฐ ํด๋ž˜์Šค ์ƒ์„ฑ
  • ์ธ์ฆ ์ปจํŠธ๋กค๋Ÿฌ ์ƒ์„ฑ

  • Swagger UI ์‚ฌ์šฉ์ž ์ง€์ •

    ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜ ์ •๋ณด ์—…๋ฐ์ดํŠธ

    ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜ ์ด๋ฆ„, ๋ฒ„์ „ ๋ฐ ์„ค๋ช…๊ณผ ๊ฐ™์€ ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜๋ณ„ ์„ธ๋ถ€ ์ •๋ณด๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ Swagger UI๋ฅผ ์‚ฌ์šฉ์ž ์ง€์ •ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค.

    Swagger์— ์ธ์ฆ ์ถ”๊ฐ€

    Swagger UI๋Š” API ์š”์ฒญ์— ์ธ์ฆ ํ—ค๋”๋ฅผ ์ถ”๊ฐ€ํ•  ์ˆ˜ ์žˆ์–ด ์ธ์ฆ๋œ ํ…Œ์ŠคํŠธ๋ฅผ ๊ฐ€๋Šฅํ•˜๊ฒŒ ํ•ฉ๋‹ˆ๋‹ค.

    1. ๋ณด์•ˆ ์Šคํ‚ค๋งˆ ๊ตฌ์„ฑ

  • JWT๋ฅผ ์‚ฌ์šฉํ•œ ์ธ์ฆ
    • Swagger UI์—์„œ "Authorize" ๋ฒ„ํŠผ์„ ํด๋ฆญํ•ฉ๋‹ˆ๋‹ค.
    • Bearer ์ ‘๋‘์‚ฌ๊ฐ€ ์žˆ๋Š” JWT ํ† ํฐ์„ ์ž…๋ ฅํ•ฉ๋‹ˆ๋‹ค (์˜ˆ: Bearer your_jwt_token).
    • ์ธ์ฆ๋˜๋ฉด Swagger๋Š” ์ดํ›„์˜ API ์š”์ฒญ์— ํ† ํฐ์„ ํฌํ•จํ•ฉ๋‹ˆ๋‹ค.

    Swagger๋กœ API ํ…Œ์ŠคํŠธํ•˜๊ธฐ

    ์ธ์ฆ๋œ ์š”์ฒญ ๋งŒ๋“ค๊ธฐ

    1. JWT ํ† ํฐ ์ƒ์„ฑ
      • ์œ ํšจํ•œ ์ž๊ฒฉ ์ฆ๋ช…์„ ์‚ฌ์šฉํ•˜์—ฌ /token ์—”๋“œํฌ์ธํŠธ๋ฅผ ์‚ฌ์šฉํ•˜๋ฉด JWT๋ฅผ ๋ฐ›์„ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค.
    2. Swagger UI ์ธ์ฆ
      • "Authorize"๋ฅผ ํด๋ฆญํ•˜๊ณ  ์•ž์„œ ์„ค๋ช…ํ•œ ๋Œ€๋กœ ํ† ํฐ์„ ์ž…๋ ฅํ•ฉ๋‹ˆ๋‹ค.
    3. ๋ณดํ˜ธ๋œ ์—”๋“œํฌ์ธํŠธ ์ ‘๊ทผ
      • ์ธ์ฆ์ด ์„ค์ •๋˜๋ฉด Swagger UI์—์„œ ์ง์ ‘ ๋ณด์•ˆ๋œ API์— ์ ‘๊ทผํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค.

    ์ƒ˜ํ”Œ ํ”„๋กœ๊ทธ๋žจ ์ฝ”๋“œ

    ์„ค๋ช…

    • ์—”๋“œํฌ์ธํŠธ: /homepage
    • ๋ฉ”์†Œ๋“œ: GET
    • ์„ค๋ช…: ๊ฐ„๋‹จํ•œ ์ธ์‚ฌ๋ฅผ ๋ฐ˜ํ™˜ํ•ฉ๋‹ˆ๋‹ค.

    ํ”„๋กœ๊ทธ๋žจ ์ถœ๋ ฅ

    http://localhost:8080/homepage์— ์ ‘๊ทผํ•˜๋ฉด ๋‹ค์Œ๊ณผ ๊ฐ™์€ ์‘๋‹ต์ด ํ‘œ์‹œ๋ฉ๋‹ˆ๋‹ค:


    ๋ชจ๋ฒ” ์‚ฌ๋ก€ ๋ฐ ๋ณด์•ˆ ๊ณ ๋ ค ์‚ฌํ•ญ

    JWT ๋น„๋ฐ€ํ‚ค์˜ ์•ˆ์ „ํ•œ ์ €์žฅ

    JWT ์„œ๋ช…์„ ์œ„ํ•œ ๋น„๋ฐ€ํ‚ค๋Š” ์ฝ”๋“œ๋ฒ ์ด์Šค์— ๋…ธ์ถœ๋˜์ง€ ์•Š๋„๋ก ์•ˆ์ „ํ•˜๊ฒŒ ์ €์žฅํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋‚˜ ๋ณด์•ˆ ๊ธˆ๊ณ ๋ฅผ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค.

    ํ† ํฐ ๋งŒ๋ฃŒ ์„ค์ •

    JWT์˜ ๋งŒ๋ฃŒ ์‹œ๊ฐ„์„ ํ•ญ์ƒ ์„ค์ •ํ•˜์—ฌ ํ† ํฐ ๋„๋‚œ ๋ฐ ๋‚จ์šฉ์˜ ์œ„ํ—˜์„ ์ตœ์†Œํ™”ํ•˜์‹ญ์‹œ์˜ค.

    HTTPS ์‚ฌ์šฉ

    ๋ชจ๋“  API ํ†ต์‹ ์ด HTTPS๋ฅผ ํ†ตํ•ด ์ด๋ฃจ์–ด์ง€๋„๋ก ํ•˜์—ฌ ์ „์†ก ์ค‘์ธ ๋ฐ์ดํ„ฐ๋ฅผ ๋ณดํ˜ธํ•˜์‹ญ์‹œ์˜ค.

    ํ† ํฐ ํด๋ ˆ์ž„ ๊ฒ€์ฆ

    JWT ๋‚ด์˜ ํด๋ ˆ์ž„(์˜ˆ: ๋ฐœ๊ธ‰์ž, ๋Œ€์ƒ, ๋งŒ๋ฃŒ)์„ ํ•ญ์ƒ ๊ฒ€์ฆํ•˜์—ฌ ํ† ํฐ์˜ ๋ฌด๊ฒฐ์„ฑ์„ ๋ณด์žฅํ•˜์‹ญ์‹œ์˜ค.

    ์˜์กด์„ฑ ์ •๊ธฐ ์—…๋ฐ์ดํŠธ

    Swagger, JWT ๋ผ์ด๋ธŒ๋Ÿฌ๋ฆฌ ๋ฐ ๊ธฐํƒ€ ์˜์กด์„ฑ์„ ์ตœ์‹  ์ƒํƒœ๋กœ ์œ ์ง€ํ•˜์—ฌ ์•Œ๋ ค์ง„ ์ทจ์•ฝ์ ์„ ํŒจ์น˜ํ•˜์‹ญ์‹œ์˜ค.


    ๊ฒฐ๋ก 

    Swagger์™€ JWT๋ฅผ Spring Boot RESTful API์— ํ†ตํ•ฉํ•จ์œผ๋กœ์จ ๊ฒฌ๊ณ ํ•œ ๋ฌธ์„œํ™”์™€ ์•ˆ์ „ํ•œ ์ธ์ฆ ๋ฉ”์ปค๋‹ˆ์ฆ˜์„ ์ œ๊ณตํ•˜์—ฌ ๊ฐœ๋ฐœ ํ”„๋กœ์„ธ์Šค๋ฅผ ํฌ๊ฒŒ ํ–ฅ์ƒ์‹œํ‚ฌ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. Swagger๋Š” API ํƒ์ƒ‰ ๋ฐ ํ…Œ์ŠคํŠธ๋ฅผ ๋‹จ์ˆœํ™”ํ•˜๊ณ , JWT๋Š” ํ™•์žฅ ๊ฐ€๋Šฅํ•œ ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜์— ์ ํ•ฉํ•œ ์•ˆ์ „ํ•˜๊ณ  ๋ฌด์ƒํƒœ ์ธ์ฆ์„ ๋ณด์žฅํ•ฉ๋‹ˆ๋‹ค. ์ด ์ „์ž์ฑ…์— ์„ค๋ช…๋œ ์ง€์นจ๊ณผ ๋ชจ๋ฒ” ์‚ฌ๋ก€๋ฅผ ๋”ฐ๋ฅด๋ฉด ๊ฐœ๋ฐœ์ž๋“ค์€ ํ˜„์žฌ์™€ ๋ฏธ๋ž˜์˜ ์š”๊ตฌ๋ฅผ ์ถฉ์กฑํ•˜๋Š” ์•ˆ์ „ํ•˜๊ณ  ์ž˜ ๋ฌธ์„œํ™”๋œ API๋ฅผ ๊ตฌ์ถ•ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค.

    ํ‚ค์›Œ๋“œ: Swagger, JWT, Spring Boot, RESTful API, API Documentation, JSON Web Token, Authentication, Authorization, Springfox, API Security, OpenAPI, Microservices, Stateless Authentication, Secure APIs

    ์ฐธ๊ณ : ์ด ๊ธฐ์‚ฌ๋Š” AI์— ์˜ํ•ด ์ƒ์„ฑ๋˜์—ˆ์Šต๋‹ˆ๋‹ค.






    Share your love