다들 알고 계시겠지만, 얼마 전에 큰 일이 있었어요.지난 목요일(5/3)에 cdn.jsdelivr.net이 접속불능에 빠졌습니다.bootstrap, jquery 등등을 저희가 link tag로 편하게 이용하고자 할 때, 무심코 접속하게 되는 사이트입니다.제가 js, css 번들을 다운 받을 필요 없이, 단지 저 link tag를 html에 삽입하는 것만으로 위 라이브러리들을 사용할 수 있어서 편하게 사용들을 했었는데요.저거 넣어서 만들었던 서비스들이 여럿 깨져있어서, cdn.jsdelivr.net이 복구 될 때까지 매우 혼란스러운 하루를 보냈었습니다.대부분의 서비스는, js, css 번들 다운 받아 붙이는 걸로 금새 복구할 수 있었는데,fastapi에는 자동으로 swagger 문서를 생성해주는 매우 편리한 기능이 있는데요.이걸 사내 api 만들어서 공유할 때 engr들이 엄청 많이 쓰고 있었는데, (사실상 fastapi를 사용하는 이유의 8할...)문제는 fastapi에서 자동으로 만드는 swagger 문서가이 두 녀석으로부터 css, js를 받아온다는 것이었습니다.fastapi에서 자동으로 생성해주는 docs endpoint에 대한 configuration 때문에 고민을 좀 했었어요. 결론적으로는 이렇게 해결하시면 됩니다.일단 swagger-ui.css 하고 swagger-ui-bundle.js 를 구합니다.저는 그냥 브라우저로 저 url에 접속해서 구해둔 게 있어서 썼는데요. 구글 검색하시면 css, js 구하실 수 있으실 거예요.얼추 project가 이렇게 구성되어 있다고 치면,app.py를 이렇게 구성하시면 됩니다. 간단한 샘플 코드니 보면 바로 이해되실 거예요.기본적으로 fastapi의 /docs endpoint는fastapi.openapi.docs 에 있는 get_swagger_ui_html 을 실행해서 출력하도록 되어 있습니다.이 부분을 원하는 대로 커스터마이징해서 실행하도록 구성하면 설정을 바꿔줄 수 있어요.저 코드를 실행하고 docs 엔드포인트에 들어가보면저렇게 swagger 문서에서 cdn.jsdelivr.net과의 의존성이 없어진 것을 확인하실 수 있습니다.

안녕하세요. LINE Plus에서 LINE Monary와 MyDashboard 서비스의 백엔드를 맡고 있는 조성빈입니다. 이번 글에서는 백엔드 서비스 개발 및 운영 업무를 담당하면서 REST API 기반의 인터페이스 문서를 가지고 다양한 파트와 커뮤니케이션을 진행하면서 겪었던 문제들과, 그 문제들을 해결한 방법을 소개하려고 합니다. 제가 말씀드리는 게 정답이라고 할 수는 없겠으나 REST API의 스펙을 효과적으로 관리하는 방안 중 하나라고는 생각하며, 이 글을 읽는 분들에게 도움이 되기를 바랍니다.API 문서를 제대로 관리하지 못할 때 발생하는 문제REST API 기반의 서비스에서 API마다 명세를 직접 문서로 작성한다고 하면, API를 추가하거나 수정할 때마다 관리 비용은 기하급수적으로 늘어납니다. 예를 들어, MSA 환경 기반의 서비스에서 관리하는 서비스 도메인이 10개일 때 각 서비스마다 30개의 API가 있다면 총 300개의 문서를 만들어야 하는 불상사가 생깁니다. '에이, 실제로 누가 그렇게 API를 문서화해서 관리해?'라고 생각할 수 있겠지만, 실제 업무에서는 다양한 이해 관계자와 커뮤니케이션할 때 API 문서가 필수 요소가 될 수 있으며, 저 역시 300개까지는 아니어도 몇 십개 수준까지는 만들어 본 기억이 있습니다. 이런 경우 API를 업데이트할 때마다 관리해야 하는데요. 당시 개발만 하기에도 바쁜 와중이어서 정말 큰 부담으로 다가왔습니다.자동 API 문서화 도구를 사용하는 것만으로 해결될까?서버 개발자가 REST API 기반에서 생성하는 API 문서로는 OpenAPI 스펙이 가장 많이 쓰이고 있습니다. OpenAPI 스펙이 구현된 springdoc 라이브러리를 이용해 Swagger UI를 도입해서 사용하면 코드 수준에서 별다른 설정 없이 API 문서를 자동으로 생성할 수 있으며 API 실행 테스트까지 할 수 있습니다.하지만! MSA 환경에서는 서비스 도메인별로 모두 도메인 URL이 다릅니다. 따라서 서비스 도메인이 10개라면 한 사람에게 10개의 Swagger URL을 알려줘야 하는 문제가 발생합니다. 만약 알파와 베타 환경이 다르다면 URL은 20개가 될 수도 있습니다.이렇게 URL이 많아지면 API 명세가 어떤 URL에 속해 있는지 찾기도 어려워 Swagger로만 커뮤니케이션하기에는 한계가 있었습니다. 또한 코드 작업을 완료했다고 해도 코드 리뷰를 거쳐 머지된 후 배포까지 완료되지 않으면 해당 스펙이 문서에 반영되지 않습니다. 따라서 문서 배포까지의 텀이 상당히 길어질 수 있기 때문에 개발 초기에 스펙을 공유해야 할 때에는 사용하기 어렵다는 이유로 문서를 다시 수동으로 작성하는 방식으로 돌아가는 문제도 발생했습니다.아래 예시를 보면, MSA 환경의 한 서비스에서 각 하위 도메인마다 각각 문서 URL이 생성되고 있습니다. 또한 문서 URL에 들어가보면 하나의 문서에 내부용, 프런트엔드용, 관리자용 등 다양한 목적의 API가 섞여 들어가 있습니다. 이 때문에 이를 참고하려는 개발자는 어떤 URL의 문서를 봐야할지, 이

안녕하세요, 힐링페이퍼 백엔드 엔지니어 Eddy입니다. 저는 현재 힐링페이퍼에서 미용 의료 병원용 SaaS 제품을 개발하고 있습니다.이번 글에서는 KOS팀에서 병원 관리 소프트웨어 KOS(이하 KOS)를 개발하면서 새로 도입한 인터페이스 정의 언어를 이용한 인터페이스 관리 전략에 대해 소개합니다.B2B SaaS 애플리케이션 개발을 시작하면서 KOS팀은 인터페이스 정의 언어 (이하 IDL, Interface Definition Language)를 도입하게 되었습니다. IDL은 소프트웨어의 인터페이스를 정의하는 명세 언어를 말하고, 특정한 언어에 국한되지 않는 방법으로 인터페이스를 정의하여 애플리케이션들의 언어가 다르더라도 동일한 인터페이스로 통신할 수 있도록 합니다.여러 종류의 IDL 중, KOS팀은 Google Protocol buffers(a.k.a. Protobuf)를 선택했습니다. KOS팀이 Protobuf를 선택한 이유는 다양한 언어로 Generate 할 수 있다는 특징이 있고, 무엇보다 인터페이스 작성이 매우 쉽습니다. 그리고 추후 gRPC라는 강력한 경량 통신을 사용할 수 있기에 도입했습니다. KOS팀은 IDL을 도입함으로써, 제품 개발 프로세스에 있던 비효율을 해결할 수 있었습니다. IDL을 도입하기 전의 제품 개발 프로세스입니다.• 프로덕트 오너와 프로덕트 디자이너가 이터레이션을 계획하고 와이어프레임을 만듭니다.• 모든 팀 구성원이 참여해 이터레이션 계획 스펙을 확정합니다.• 프로덕트 디자이너가 제품을 디자인합니다.• 백엔드 개발자가 API를 설계하고 노션 문서에 API 명세를 작성(또는 Swagger)합니다.• 프론트엔드 개발자가 해당 인터페이스가 계획된 제품 구현을 반영할 수 있는 스펙인지 확인합니다.위 프로세스의 4, 5번 과정에서 비효율적인 문제들이 발생하곤 했는데요. 자세하게 어떤 비효율적인 문제가 있었고, IDL을 통해 어떻게 해결했는지에 대해 이야기 해보겠습니다.백엔드 개발자가 인터페이스를 주도하여 설계할 때, 데이터 무결성 및 시스템 성능 최적화와 같은 시스템적인 부분이 가장 먼저 고려되는 경우가 많습니다. 이는 기술적 측면에 있어 분명 필수적인 고려 사항이지만 성능에 초점이 맞춰지다 보니 오버 스펙을 가진 인터페이스가 정의될 여지가 생기며, 이로 인해 프론트엔드 개발자와 이를 통합하기 위해 지속적인 합의를 하게 됩니다. 해당 과정에서 커뮤니케이션 오버헤드가 발생하고 운영 비용이 높아질 수 있다는 문제가 있습니다.이제 이러한 비효율적인 문제를 해결하기 위해 어떠한 변경들이 있었는지 설명드리겠습니다.프론트엔드 주도로 인터페이스를 설계한다백엔드 주도로 인터페이스를 설계하면서 직면한 문제를 대응하기 위해 설계 프로세스를 변경했습니다. 이제 UI와 UX 디자인의 복잡성에 대해 더 잘 알고 있는 프론트엔드 개발자가 인터페이스 설계를 주도하여 최종 엔드 유저의 요구 사항과 기대에 부합하는 방식으로 인터페이스를 설계합니다.또한, 이 변경된 프로세스를 통해 백엔드와 프론트엔드 개발자 간 지식 전파도 자연스럽게 이어집니다.

• None 최근 Gradle을 많이 사용하고 있어 이번에는 Gradle 설정을 알아보면 좋을듯 하다.• None 이번 아티클에서는 petstore.yaml 을 이용하여 openapi generator 를 통해 서버사이드 코드를 생성해 보겠다.• None 이전 아티클에서는 maven 플러그인을 이용했지만 이번에는 gradle 플러그인을 이용하여 생성해 볼 것이다.• None 우선 start.spring.io 에서 다음 설정으로 프로젝트를 생성하자.• None build.gradle 파일을 열고 다음과 같이 추가하자.• None org.openapi.generator 버젼을 6.5.0으로 설정한다. openpai generator의 플러그인이다.• None com.diffplug.eclipse.apt 버젼을 3.26.0 으로 설정한다. 이는 eclipse에서 필요한경우 사용할 수 있다.• None 위 코드는 스프링부트 2.7.x 버젼과 3.0.6 버젼용으로 되어 있으니 버젼에 따라 지정하면 된다.• None 이제 필요한 의존성을 설정하자. 아래와 같이 구역을 구분하여 설정하였다.• None• None 이 영역에는 스프링부트를 위한 기본 설정이 지정되었다.• None• None Swagger 적용을 위한 위치이다. 부트 2.7.X 버젼에서는 이 설정이 필요하다.• None 참고: 3.0.x 의 스프링부트의 경우 주석을 교체해주자.• None springdoc-openapi-starter-webmvc-ui: 2.1.0 만으로 이전 버젼의 다양한 설정을 대체할 수 있다.• None• None openapi-generator-gradle-plugin:5.1.1 이는 openapi generator를 위한 gradle 플러그인이다 .• None 참고: 3.0.x 의 스프링부트의 경우 주석을 교체해주자.- jackson-databind-nullable:0.2.6 REST API용으로 application/json을 변환하기 위한 패키지 - validation-api:2.0.1.Final 스키마(데이터객체) 검증을위한 패키지 - javax.annotation-api:1.3.2 openapi에서 사용하는 어노테이션 처리용 패키지 - javax.servlet-api:4.0.1 웹 엔드포인트를 생성하기 위한 서블릿 패키지 - spring-boot-starter-validation 스프링부트 데이터 검증을위한 패키지 - httpclient5:5.2.1 http 요청을 위한 클라이언트 패키지• None 위와 같이 의존성 파일을 설정해 주어야 정상적으로 openapi generator로 스켈레톤 코드를 생성해 낼 수 있다.• None 이제 openApiGenerate를 위한 gradle 태스크를 생성하자.• None openapi plugin은 openApiGenerate를 참조하게 된다.• None• None true로 설정한 경우 생성되는 로그를 확인할 수 있다.• None• None 스프링 전용 코드를 생성하라는 의미이다. 이는 generator 가 어떠한