Swagger를 사용하여 Beego에서 자동으로 API 문서 생성

Beego에서 Swagger를 사용하여 자동으로 API 문서 생성

인터넷 기술이 점점 성숙해지면서 점점 더 많은 기업이 비즈니스 모델을 디지털 방식으로 전환하기 시작하고 있으며 디지털 전환의 중요한 부분인 API도 점점 더 중요해지고 있습니다. . API를 개발할 때, API의 보안성과 신뢰성을 확보하는 것 외에도, 자신이 개발한 API를 다른 프런트엔드, 백엔드 개발 엔지니어가 어떻게 빠르게 이해하고 사용할 수 있도록 하는가도 매우 중요한 부분입니다. 이 기사에서는 다른 개발 엔지니어의 호출 및 사용을 용이하게 하기 위해 Beego 프레임워크를 사용하여 API를 개발할 때 Swagger 도구를 사용하여 API 문서를 자동으로 생성하는 방법을 소개합니다.

Swagger란 무엇인가요?

Swagger는 API 개발 및 사용을 단순화하고 표준화하는 것을 목표로 하는 오픈 소스 API 사양 및 도구 세트입니다. 개발자, 소비자 및 문서 간의 대화형 인터페이스를 자동으로 생성할 수 있으며 다양한 시각적 도움말 문서 기능을 제공합니다.

Swagger를 사용하는 이유는 무엇인가요?

일부 API에는 사용법과 호출 방법을 이해하는 데 도움이 되는 문서와 설명이 필요합니다. Swagger를 사용하면 이러한 문서를 단순화하고 자동으로 생성할 수 있습니다. Swagger 도구를 사용하면 API 문서를 더욱 아름답고 표준화하며 생성 시 읽기 쉽게 만들 수 있습니다. Swagger의 필수 형식은 개발자가 표준화된 사양을 준수하는 API를 설계 및 구현하는 데 도움을 주어 시간과 에너지를 절약할 수 있습니다.

Beego에서 Swagger 사용

1. 종속성 추가

Beego 프로젝트에서 Swagger를 사용하려면 먼저 Swagger 라이브러리의 종속성을 프로젝트에 추가해야 합니다. 다음 명령을 통해 설치할 수 있습니다:

go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/gin-swagger/swaggerFiles

2. Edit Swagger comments

Beego 프레임워크에서는 라우터 코드의 주석을 사용하여 API 매개변수, 요청 유형, 반환 값 및 기타 정보를 설명합니다. Swagger를 사용할 때 필요합니다. API 문서를 자동으로 생성하려면 이러한 주석에 Swagger 사양 태그를 추가하세요.

다음은 간단한 예입니다.

// @Summary  获取一个用户信息
// @Description 通过ID获取一个用户信息
// @Accept  json
// @Produce  json
// @Param   id     path    int     true        "用户ID"
// @Success 200 {object} models.User
// @Router /users/{id} [get]
func GetUser(c *gin.Context) {
    // ...
}

댓글에 몇 가지 특수 사양 태그를 추가했습니다.

• @Summary: API 메서드 개요
• @Description: API 메서드에 대한 자세한 설명
• @Accept: 허용되는 콘텐츠 -Type type
• @Produce: 응답 콘텐츠 유형 type
• @Param: 매개변수 이름, 위치, 데이터 유형, 필수 여부 및 설명을 포함한 요청 매개변수입니다.
• @Success: 성공적인 응답의 HTTP 상태 코드 및 반환 값 유형으로, 배열, 구조 및 기타 정보도 포함될 수 있습니다.
• @Router: 요청 경로 및 요청 방법.

필요에 따라 API 설명을 보완하기 위해 더 많은 태그를 추가할 수 있습니다.

3. 자동으로 문서 생성

Swagger 사양 주석을 코드에 추가한 후 프로젝트의 루트 디렉터리에서 다음 명령을 실행하여 API 문서를 생성합니다.

swag init

이 명령은 프로젝트 디렉터리 A docs 폴더에 생성됩니다. , 생성된 API 문서와 정적 리소스 파일이 포함됩니다.

4. SwaggerUI를 사용하여 API 문서 보기

생성된 문서를 프런트엔드 개발자에게 직접 보내면 불필요한 부담을 갖게 됩니다. API 문서를 보다 친숙하고 사용하기 쉽게 만들기 위해 SwaggerUI를 도입하여 API 문서를 볼 수 있습니다.

먼저 SwaggerUI 정적 리소스 파일을 프로젝트에 복사한 다음 /swagger/*any 경로를 사용하여 라우터를 생성하여 SwaggerUI를 프로젝트와 연결할 수 있습니다.

r.StaticFS("/swagger", http.Dir("docs"))

다음으로 브라우저에서 http:/를 방문하세요. /localhost:8080/swagger/index.html 자동으로 생성된 API 문서를 확인하세요.

요약

Beego에서 Swagger를 사용하면 주석을 통해 API 정의를 표준화하고 개발자가 쉽게 사용할 수 있는 아름다운 API 문서를 생성할 수 있습니다. 동시에 SwaggerUI를 도입하면 API 표시 및 상호 작용을 더욱 단순화하고 개발을 가속화할 수 있습니다.

참고자료:

https://www.cnblogs.com/wuyun-blog/p/10540875.html

https://github.com/swaggo/gin-swagger

https://github.com / 스웨고/스웨그

위 내용은 Swagger를 사용하여 Beego에서 자동으로 API 문서 생성의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!