API 온라인 문서 자동화를 위해 Golang에서 SwaggerUI 사용

API 온라인 문서 자동화를 위해 Golang에서 SwaggerUI 사용

API(애플리케이션 프로그래밍 인터페이스)의 사용은 현대 애플리케이션 개발에서 필수 요소가 되었습니다. API를 사용하면 프런트엔드와 백엔드 분리, 마이크로서비스 및 클라우드 애플리케이션이 더 쉬워집니다. 그러나 좋은 API는 단순히 기능을 구현하는 것이 아니라 사용자 친화적이고 사용하기 쉽습니다. 이러한 이유로 문서화된 API가 점점 더 중요해지고 있습니다. 온라인 문서의 장점은 API를 작동하기 전에 API에 대해 배울 수 있다는 것입니다.

이 기사에서는 SwaggerUI를 사용하여 API 문서를 기록하는 방법과 Golang에서 이 프로세스를 자동화하여 유지 관리를 더 쉽게 만들고 읽을 수 있는 문서를 제공하며 다른 팀과 파트너가 API를 쉽게 이해할 수 있도록 하는 방법을 소개합니다.

SwaggerUI는 API용 문서 작성, 대화형 API 문서 생성, 시각적 방식으로 API 설명에 널리 사용되는 도구이며, 사람이 읽을 수 있는 문서와 기계가 읽을 수 있는 JSON 또는 YAML을 모두 생성할 수 있습니다. SwaggerUI는 Golang을 포함한 많은 프로그래밍 언어와 통합됩니다.

먼저 SwaggerUI - Swag의 Golang 구현을 사용해야 합니다. Swag는 Go 언어 주석과 Swagger 주석을 결합하여 Swagger 2.0 문서를 자동으로 생성하는 자동화된 API 문서 도구입니다.

1단계: Swag 설치

터미널/cmd에서 다음 명령을 사용하여 Swag를 다운로드하고 설치합니다.

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

2단계: 코드에 Swagger 주석 추가

코드에 Swagger 주석을 추가하여 API를 설명합니다.

HTTP 핸들러 함수 위의 주석에 Swagger 주석을 추가합니다. 예:

// GetByID godoc
// @Summary Get user details by ID
// @Description Get user details by ID
// @Tags user
// @Accept json
// @Produce json
// @Param id path int true "User ID"
// @Success 200 {object} model.User
// @Failure 400 {object} ErrorResponse
// @Router /users/{id} [get]
func GetByID(c *gin.Context) {
    //…code here…
}

3단계: Swagger JSON 파일 생성

다음 명령을 사용하여 코드베이스 루트에 Swagger JSON 파일을 생성합니다.

swag init

This 명령은 코드에서 Swagger 주석을 사용하고 Swagger JSON 파일을 생성합니다. 프로젝트의 Makefile에 추가할 수도 있습니다.

4단계: SwaggerUI 통합

Swag는 브라우저에 API 문서를 표시하기 위한 프런트 엔드로 SwaggerUI를 사용하여 SwaggerUI의 파일을 애플리케이션에 정적으로 역프록시해야 합니다.

Golang 애플리케이션이 포트 8080에서 실행되고 있다고 가정합니다. 우리가 사용할 SwaggerUI 버전은 v3.31.1입니다. 공식 SwaggerUI GitHub 페이지에서 다음을 통해 다운로드할 수 있습니다.

curl -L https://github.com/swagger-api/swagger-ui/archive/v3.31.1.tar.gz -o swagger-ui.tar.gz
tar -xf swagger-ui.tar.gz

이렇게 하면 SwaggerUI의 모든 파일이 포함된 swagger-ui 폴더가 로컬 디렉터리에 생성됩니다. nginx를 역방향 프록시 서버로 사용하고(Apache, Caddy 등을 사용할 수 있음) 터미널/cmd에서 다음 명령을 사용하여 nginx를 시작합니다.

nginx -c /path/to/nginx.conf

nginx.conf 파일에 다음을 추가해야 합니다.

http {
  server {
    listen 8081; # 访问静态文件的端口
    server_name _;
    root /path/to/swagger-ui/dist;

    location / {
      try_files $uri $uri/ @go;
    }

    location @go {
      proxy_redirect off;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_pass http://127.0.0.1:8080; # 代理请求的端口
    }

    location /swagger-ui/ {
      try_files $uri $uri/ =404;
    }
  }
}

위의 nginx 구성에서는 정적 SwaggerUI 폴더 /swagger-ui/dist 디렉터리를 nginx 서버의 루트 디렉터리에 정적 파일로 추가합니다. 모든 요청을 포트로 전달하여 localhost:8080(자체 애플리케이션)으로 프록시합니다. 8081은 수신 대기 포트입니다. http://localhost:8081/swagger-ui/를 방문하여 SwaggerUI를 보고 사용합니다.

5단계: API 문서 보기

브라우저에서 http://localhost:8081/swagger-ui/를 방문하면 SwaggerUI 애플리케이션이 루트 디렉터리에 있는 SwaggerUI 정적 폴더를 표시합니다. 이 페이지에서 잘 문서화된 모든 API 목록을 찾을 수 있습니다. 보려는 API 문서를 클릭하면 오른쪽에 표시됩니다. 웹사이트는 API에서 직접 API 문서를 테스트하고 볼 수 있는 API 사용자 친화적인 인터페이스를 제공합니다. 이 과정에서 GUI는 이 API의 매개변수 제공, 본문 정보, API 버전, API 형식 등 Swagger 주석에 의해 자동으로 추출된 세부 정보를 표시합니다. 이를 통해 문서 작성에 소요되는 시간과 에너지를 크게 절약할 수 있습니다.

결론

API 문서는 API 설계 및 개발 프로세스에서 중요한 도구이므로 애플리케이션 구축 시 문서화된 API를 고려해야 합니다. 자동화 도구인 Swag를 사용하면 Golang에서 API 문서를 쉽게 자동화할 수 있습니다. 문서화된 API를 보고 테스트하기 위한 시각화 도구로 SwaggerUI를 사용하는 것도 매우 편리합니다. 이는 다른 팀과 협업 파트너에게 도움이 되며 API를 더 쉽게 이해할 수 있게 해줍니다.

위 내용은 API 온라인 문서 자동화를 위해 Golang에서 SwaggerUI 사용의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!