Swagger 문서 사용 규칙

1. swagger. go 파일
사용문서 설명 을 포함 하 는 모든 가방 가 져 오기

package main
import (
    _ "github.com/teambition/swaggo/example/pkg/api"
)
// @Version 1.0.0
// @Title Swagger Example API
// @Description Swagger Example API
// @Schemes http,wss
// @Host 127.0.0.1:3000
// @BasePath /api
// @Name teambition
// @Contact [email protected]
// @URL http://teambition.com
// @TermsOfServiceUrl http://teambition.com/
// @License Apache
// @LicenseUrl http://teambition.com/
// @Consumes json,xml
// @Produces json,xml

@ Version API 버 전 번호
@ 제목 서비스 이름
@ 설명 서비스 설명
@ Schemes 서비스 프로 토 콜 (http, websockes)
@ Host 사용 가능 한 서버 주소, 테스트 에 사용
@ BasePath API 경로 의 접두사
@ Name 작성 자 이름
@ 연락처 작성 자 연락처
@ URL 작성 자 개인 페이지
@ TermSOf ServiceUrl 서비스 약관 설명 주소
@ License 오픈 소스 프로 토 콜
@ License Url 프로 토 콜 주소
@ Consumes 방법 수신 매개 변수의 유형, 다 중 선택, 분리, 포함 (json, xml, plain, form, formData, stream)
@ Produces 방법 은 인자 의 유형 을 되 돌려 줍 니 다. (json, xml, plain, html, form, formData, stream)
2. 컨트롤 러 설명

// @Private reason
// @Name Controller
// @Description test apis
type Controller struct {
}

@ Private 은 이 컨트롤 러 의 모든 API 문 서 를 공개 하지 않 음 을 표시 합 니 다.

reason 사유 설명, 선택 가능 값

@ Name 자원 이름
@ 설명 자원 설명
3. 핸들 러 주해

// @Private reason
// @Title Hello
// @Summary say hello
// @Description this is a method to say hello
// @Deprecated true
// @Consumes json
// @Produces json
// @Param some_id path int true "Some ID"
// @Param offset query int true "Offset"
// @Param limit query int true "Limit"
// @Success 200 StructureWithEmbededPointer "Success!"
// @Failure 400 APIError "We need ID!!"
// @Failure 404 APIError "Can not find ID"
// @Router GET /say/hello/{some_id}
func (c *Controller) Hello(rw http.ResponseWriter, req *http.Request) {
}

@ Private 이 존재 합 니 다. 이 API 문 서 를 공개 하지 않 음 을 표시 합 니 다.
@ Title 방법 명
@ Summary 방법 안내
@ 설명 방법 에 대한 상세 한 설명
@ Deprecated 이 인 터 페 이 스 는 더 이상 사용 하지 않 습 니 다.
@ Consumes 방법 수신 매개 변수의 유형, 다 중 선택, 분리, 포함 (json, xml, plain, form, formData, stream)
@ Produces 방법 은 인자 의 유형 을 되 돌려 줍 니 다. (json, xml, plain, html, form, formData, stream)
@ Param 매개 변수 목록, 빈 칸 으로 구분

// @Param some_id path int true "Some ID" 6

some_id 매개 변수 이름

path 매개 변수 유형, (path: 경로 매개 변수, query: 요청 매개 변수, 헤더: 요청 헤더, form: 폼, body: 요청 체)

int 데이터 형식, Golang 네 이 티 브 형식 지원 (int, string, bool...), 사용자 정의 형식 지원 (your package. YourType)

true 매개 변수 가 필요 한 지, 선택 가능 한 값, 사용 - 차지

"Some ID" 파라미터 에 대한 간략 한 설명, 선택 가능 한 값, 사용 - 차지

6 기본 값, 선택 가능 값

@ Success 는 예 시 를 성공 적 으로 되 돌려 주 고 빈 칸 으로 격 리 했 습 니 다.

// @Success 200 StructureWithEmbededPointer "Success!"

200 http 반환 코드

Structure With EmbededPointer 는 데이터 형식 을 되 돌려 줍 니 다. Golang 원본 형식 ([] int, int, string, bool...) 을 지원 하고 사용자 정의 형식 (your package. YourType)

을 지원 합 니 다.

"성공!" 결과 설명, 반드시

@ Failure 가 실 패 했 습 니 다. 예 시 를 되 돌려 줍 니 다. 빈 칸 으로 구분 합 니 다.
@ Router 경로 정의, 빈 칸 으로 분리

// @Router GET /say/hello/{some_id}

GET 요청 방법, 지원 (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)

/ say / hello / {some id} 경로, {some id} 은 * * @ Param * * 에서 정의 합 니 다

4. Go 구조 체 라벨

type SimpleStructure struct {
    Id float32 `json:"id" swaggo:"true,my id,19"`
    Name string `json:"name" swaggo:"true,,xus"`
    Age int `json:"age" swaggo:"true,the user age,18"`
    CTime time.Time `json:"ctime" swaggo:"true,create time"`
    Sub subpackage.SimpleStructure `json:"sub" swaggo:"true"`
    I TypeInterface `json:"i" swaggo:"true"`
}

swaggo: "true, dfsdfdsf, 19" swagger 문서 관련 태그, 사용, 분리

true 가 필요 한 지, 선택 가능 한 값, 절약 용, 분리

my id 문서 설명, 선택 가능 한 값, 절약, 분리

19 기본 값, 선택 가능 값, 절약, 분리

전송 주소:

 https://github.com/teambition/swaggo/wiki/Declarative-Comments-Format#1-swaggergo