gindocnic

README

Gindocnic

A library for generating OpenAPI 3.1 documentation for the Gin Web Framework.

Usage

A basic example:

doc := NewDoc()
r := gin.Default()

request := struct {
    Id int `json:"id" binding:"required"`
}{}
spec := func(p *PathItemSpec) {
    p.AddRequest(request)
}
r.POST("/pets", doc.Operation(func(c *gin.Context) {}, spec))
if err := doc.AssocRoutesInfo(r.Routes()); err != nil {
    log.Fatalf("%#v", err)
}
yml, err := doc.MarshalYAML()
if err != nil {
    log.Fatalf("%#v", err)
}
fmt.Println(string(yml))

Output:

openapi: 3.1.0
info:
  title: ""
  version: ""
paths:
  /pets:
    post:
      operationId: pets0
      requestBody:
        content:
          application/json:
            schema:
              properties:
                id:
                  type: integer
              required:
              - id
              type: object
      responses:
        "204":
          description: No Content
      summary: ""

Further examples are available in the API documentation on go.dev.

Contributing

• The layout of this module loosely follows a basic layout for Go application projects.

Documentation

Overview

Package gindocnic is a library for generating OpenAPI3.1 documentation for the Gin Web Framework.

Example

doc := NewDoc()
r := gin.Default()

request := struct {
	Id int `json:"id" binding:"required"`
}{}
spec := func(p *PathItemSpec) {
	p.AddRequest(request)
}
r.POST("/pets", doc.Operation(func(c *gin.Context) {}, spec))
if err := doc.AssocRoutesInfo(r.Routes()); err != nil {
	log.Fatalf("%#v", err)
}
yml, err := doc.MarshalYAML()
if err != nil {
	log.Fatalf("%#v", err)
}
fmt.Println(string(yml))

Output:
openapi: 3.1.0
info:
  title: ""
  version: ""
paths:
  /pets:
    post:
      operationId: pets0
      requestBody:
        content:
          application/json:
            schema:
              properties:
                id:
                  type: integer
              required:
              - id
              type: object
      responses:
        "204":
          description: No Content
      summary: ""

Index

• func RequestContentType(contentType string) func(ro *requestOptions)
• func ResponseStatus(status int) responseOption
• type Doc
  • func NewDoc() *Doc
  • func (d *Doc) AssocRoutesInfo(routes gin.RoutesInfo) error
  • func (d *Doc) MarshalYAML() ([]byte, error)
  • func (d *Doc) Operation(h gin.HandlerFunc, opts ...PathItemSpecFunc) gin.HandlerFunc
  • func (d *Doc) WithLicense(name, url string) *Doc
  • func (d *Doc) WithSecurity(securities map[string][]string) *Doc
  • func (d *Doc) WithServer(url string) *Doc
  • func (d *Doc) WithSummary(summary string) *Doc
• type PathItemSpec
  • func (o *PathItemSpec) AddRequest(body any, opts ...requestOption)
  • func (o *PathItemSpec) AddResponse(body any, opts ...responseOption)
  • func (o *PathItemSpec) SetMethod(method string)
  • func (o *PathItemSpec) SetPath(path string)
  • func (o *PathItemSpec) SetSummary(s string)
• type PathItemSpecFunc
  • func OperationMethod(method string) PathItemSpecFunc
  • func OperationSummary(summary string) PathItemSpecFunc
  • func PathItemSpecPath(path string) PathItemSpecFunc

Examples

• Package

Functions

func RequestContentType

func RequestContentType(contentType string) func(ro *requestOptions)

RequestContentType リクエストのContent-Typeを設定します。 AddRequestの可変長引数に渡してください。

func ResponseStatus

func ResponseStatus(status int) responseOption

Types

type Doc

type Doc struct {
	// contains filtered or unexported fields
}

Doc represents the root of an OpenAPIv3.1 document.

func NewDoc

func NewDoc() *Doc

NewDoc returns `*Doc`.

func (*Doc) AssocRoutesInfo

func (d *Doc) AssocRoutesInfo(routes gin.RoutesInfo) error

AssocRoutesInfo リクエストハンドラをパスやHTTPメソッドと関連づけて、Open API仕様書に必要な情報をそろえます。

func (*Doc) MarshalYAML

func (d *Doc) MarshalYAML() ([]byte, error)

MarshalYAML returns the YAML encoding of Doc.

func (*Doc) Operation

func (d *Doc) Operation(h gin.HandlerFunc, opts ...PathItemSpecFunc) gin.HandlerFunc

Operation configures the path item schema for the HTTP path and method that the handler is registered to.

func (*Doc) WithLicense

func (d *Doc) WithLicense(name, url string) *Doc

WithSummary [info-object]のlicenseを登録します。 [info-object]: https://spec.openapis.org/oas/v3.1.0.html#info-object

func (*Doc) WithSecurity

func (d *Doc) WithSecurity(securities map[string][]string) *Doc

WithSecurity [Security Scheme Object]を登録します。 一部のAPIで求められる認証の形式を宣言します。Basic認証やOpen ID Connectなどを指定できます。 Open APIの仕様上必須のフィールドらしいです。 [Security Scheme Object]: https://spec.openapis.org/oas/v3.1.0.html#security-scheme-object

func (*Doc) WithServer

func (d *Doc) WithServer(url string) *Doc

WithServer [server]を登録します。 [server]: https://spec.openapis.org/oas/v3.1.0.html#server-object

func (*Doc) WithSummary

func (d *Doc) WithSummary(summary string) *Doc

WithSummary [info-object]のsummaryを登録します。 [info-object]: https://spec.openapis.org/oas/v3.1.0.html#info-object

type PathItemSpec

type PathItemSpec struct {
	// contains filtered or unexported fields
}

PathItemSpec [path-item-object]の生成に必要な情報をもちます。 もともとはOperationOptionsという名前でしたが、[コードレビューのコメント]とoperationより上位の path-itemのスキーマにあるhttp methodやpathを含む構造体なので、PathItemSpecに名前を変えました。 [コードレビューのコメント]: https://github.com/alpdr/data-platform/pull/481#discussion_r1804170012 [path-item-object]: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#path-item-object

func (*PathItemSpec) AddRequest

func (o *PathItemSpec) AddRequest(body any, opts ...requestOption)

AddRequest configures operation request schema.

func (*PathItemSpec) AddResponse

func (o *PathItemSpec) AddResponse(body any, opts ...responseOption)

func (*PathItemSpec) SetMethod

func (o *PathItemSpec) SetMethod(method string)

func (*PathItemSpec) SetPath

func (o *PathItemSpec) SetPath(path string)

func (*PathItemSpec) SetSummary

func (o *PathItemSpec) SetSummary(s string)

type PathItemSpecFunc

type PathItemSpecFunc func(o *PathItemSpec)

PathItemSpecFunc

func OperationMethod

func OperationMethod(method string) PathItemSpecFunc

OperationMethod

func OperationSummary

func OperationSummary(summary string) PathItemSpecFunc

OperationSummary

func PathItemSpecPath

func PathItemSpecPath(path string) PathItemSpecFunc

PathItemSpecPath