OpenAPI/Swagger를 사용하여 Go 언어로 API 문서 작성

최근에는 인터넷 기술이 지속적으로 발전하면서 Web API 인터페이스의 중요성이 더욱 중요해졌고, API 문서 작성은 개발 작업의 중요한 부분이 되었습니다. Go 언어에서는 OpenAPI/Swagger를 사용하여 API 문서를 작성할 수 있습니다.

OpenAPI/Swagger는 RESTful 아키텍처 스타일을 준수하는 API 인터페이스를 구축하고 설명하는 데 도움이 되는 API 사양 및 도구 체인입니다. 여기에는 표준화된 API 설명 언어 세트와 API 문서, 클라이언트 코드 및 서버 프레임워크를 자동으로 생성하는 데 도움이 되는 일련의 도구가 포함되어 있습니다.

Go 언어에서는 Swagger의 공식 Go 구현 "swag"를 사용하여 API 문서를 빠르게 생성할 수 있습니다. 아래에서는 swag를 사용하여 API 문서를 작성하는 방법을 알아봅니다.

먼저 프로젝트에 swag를 추가해야 합니다. 다음 명령을 사용하여 프로젝트에 추가할 수 있습니다.

go get -u github.com/swaggo/swag/cmd/swag

swag를 설치한 후 main.go 파일에 swag 관련 패키지를 가져와야 합니다.

import (
    "github.com/swaggo/files"
    "github.com/swaggo/gin-swagger"
    "github.com/gin-gonic/gin"
)

// 注册swag
func setUpSwagger(engine *gin.Engine) {
    engine.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
}

func main() {
    // 初始化 gin 引擎
    engine := gin.Default()
    setUpSwagger(engine)
    router.LoadRouters(engine)
    _ = engine.Run()
}

다음으로 인터페이스 주석에 Swagger 주석을 사용하여 인터페이스를 설명할 수 있습니다. 예:

// User register router
// @Summary User register router
// @Description User register router
// @Tags Users
// @Accept  json
// @Produce  json
// @Param user_in body models.NewUser true "user info"
// @Success 200 {string} json "{"code":200,"data":null,"msg":"Register successful"}"
// @Failure 400 {string} json "{"code":400,"msg":"Bad Request"}"
// @Router /users/register [post]
func Register(c *gin.Context) {
    name := c.PostForm("name")
    password := c.PostForm("password")
    ...
}

댓글에서는 몇 가지 Swagger 주석을 사용합니다.

• @Summary: 인터페이스 요약 정보
• @Description: 인터페이스 세부 설명
• @Tags: 인터페이스 태그
• @Accept: 인터페이스 요청 Content -Type
• @Produce: 인터페이스 응답 Content-Type
• @Param: 매개변수 위치, 매개변수 이름, 필수 매개변수인지 여부, 매개변수 설명 및 매개변수 예시를 포함한 인터페이스 매개변수 설명
• @Success: 인터페이스 성공 응답 설명, 다음을 수행할 수 있습니다. 응답 코드, 응답 정보 및 응답 데이터 구조 포함
• @Failure: 인터페이스 실패 응답 설명, 응답 코드 및 응답 정보도 포함될 수 있음

마지막으로 프로젝트 루트 디렉터리에서 swag init 명령을 사용하여 API 문서. 문서가 docs 디렉터리에 생성됩니다.

swag init

이제 http://localhost:8080/swagger/index.html을 방문하여 API 문서를 볼 수 있습니다.

일반적으로 OpenAPI/Swagger를 사용하여 API 문서를 작성하면 인터페이스를 더 명확하게 설명하고 더 쉽게 읽고 이해할 수 있습니다. Go 언어의 스웨그 라이브러리는 API 문서를 빠르게 생성할 수 있어 보다 효율적으로 개발할 수 있습니다.

위 내용은 OpenAPI/Swagger를 사용하여 Go 언어로 API 문서 작성의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!