Swagger Plugin
ここを見ながら頑張ります。
https://github.com/favclip/ucon/tree/master/sample/swagger
まとめ
- 難しい！！
- [serverName]/api/swagger.jsonでJSONファイルを取得できる
- swagger.NewHandlerInfoでhandlerをwrapしよう
- swagger.NewPlugin(*Options)で作成
- ucon.DefaultMux.Prepare()でPlugin起動
- swagger.NewHandlerInfoでwrapしたものはucon.HandlerFuncではなくucon.Handleで登録する！
- swagger-uiで見るにはすべてのAPIでJSONを返す必要がある？（HTTP Statusのみでも）
Swagger Pluginを作成する
plugin.go
// NewPlugin returns new swagger plugin configured with the options.
func NewPlugin(opts *Options) *Plugin {
if opts == nil {
opts = &Options{}
}
plugin := &Plugin{
options: opts,
swagger: opts.Object,
typeSchemaMapper: make(map[reflect.Type]*TypeSchema),
}
for k, v := range DefaultTypeSchemaMapper {
plugin.typeSchemaMapper[k] = v
}
var _ ucon.HandlersScannerPlugin = plugin
return plugin
}
&swagger.Optionを引数にして新しいPluginを返しています。
DefaultTypeSchemaMapperから定義済のschemaを登録しています。
var _ ucon.HandlersScannerPlugin = pluginはGoでよく見る、右辺が左辺のInterfaceを実装しているかを確認する処理です。
swagger.Option.Object
swagger.Option.Object
type Options struct {
Object *Object
DefinitionNameModifier func(refT reflect.Type, defName string) string
}
// Object is https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swagger-object
type Object struct {
Swagger string `json:"swagger" swagger:",req,d=2.0"`
Info *Info `json:"info" swagger:",req"`
Host string `json:"host,omitempty"`
BasePath string `json:"basePath,omitempty"`
Schemes []string `json:"schemes,omitempty" swagger:",d=https"`
Consumes []string `json:"consumes,omitempty" swagger:",d=application/json"`
Produces []string `json:"produces,omitempty" swagger:",d=application/json"`
Paths Paths `json:"paths" swagger:",req"`
Definitions Definitions `json:"definitions,omitempty"`
Parameters ParametersDefinitions `json:"parameters,omitempty"`
Responses ResponsesDefinitions `json:"responses,omitempty"`
SecurityDefinitions SecurityDefinitions `json:"securityDefinitions,omitempty"`
Security []SecurityRequirement `json:"security,omitempty"`
Tags []*Tag `json:"tags,omitempty"`
ExternalDocs *ExternalDocumentation `json:"externalDocs,omitempty"`
}
swaggerで定義されているSchemaのObjectでしょうかね。。
Pluginを登録
register_plugin
///// core.go /////
// Plugin can append Plugin to ServeMux.
func Plugin(plugin interface{}) {
DefaultMux.Plugin(plugin)
}
// Plugin can append Plugin to ServeMux.
func (m *ServeMux) Plugin(plugin interface{}) {
p, ok := plugin.(*pluginContainer)
if !ok {
p = &pluginContainer{base: plugin}
}
p.check()
m.plugins = append(m.plugins, p)
}
///// plugin.go /////
type pluginContainer struct {
base interface{}
}
func (p *pluginContainer) check() {
if p.HandlersScanner() != nil {
return
}
panic(fmt.Sprintf("unused plugin: %#v", p.base))
}
// HandlersScanner returns itself if it implements HandlersScannerPlugin.
func (p *pluginContainer) HandlersScanner() HandlersScannerPlugin {
if v, ok := p.base.(HandlersScannerPlugin); ok {
return v
}
return nil
}
// HandlersScannerPlugin is an interface to make a plugin for scanning request handlers.
type HandlersScannerPlugin interface {
HandlersScannerProcess(m *ServeMux, rds []*RouteDefinition) error
}
全体的に登録したいPluginがHandlersScannerPluginを実装していればPluginに登録可能のようです。
Pluginを使う
ucon.DefautlMux.Prepare()を実行します
core.go
// Prepare the ServeMux.
// Plugin is not show affect to anything.
// This method is enabled plugins.
func (m *ServeMux) Prepare() {
for _, plugin := range m.plugins {
used := false
if sc := plugin.HandlersScanner(); sc != nil {
err := sc.HandlersScannerProcess(m, m.router.handlers)
if err != nil {
panic(err)
}
used = true
}
if !used {
panic(fmt.Sprintf("unused plugin: %#v", plugin))
}
}
}
先ほど登録したpluginsを実行しています。
plugin.HandlersScanner() == nilの場合はused == falseのままなのでpanicするようです。
Swagger PluginのHandlersScannerProcess(m, m.router.handlers)を見る
Pluginが実行されるのは、HandlersScannerProcess(m, m.router.handlers)なので、
Swagger Pluginで実装されている箇所を見ていきます。
plugin.go
// HandlersScannerProcess executes scanning all registered handlers to serve swagger.json.
func (p *Plugin) HandlersScannerProcess(m *ucon.ServeMux, rds []*ucon.RouteDefinition) error {
// construct swagger.json
for _, rd := range rds {
err := p.processHandler(rd)
if err != nil {
return err
}
}
err := p.swagger.finish()
if err != nil {
return err
}
// supply swagger.json endpoint
m.HandleFunc("GET", "/api/swagger.json", func(w http.ResponseWriter, r *http.Request) *Object {
return p.swagger
})
return nil
}
p.processHandler(*ucon.RouteDefinition)→p.swagger.finish()→m.HandlerFuncの順に実行されています。
順番に見ていきます。
p.processHandler(*ucon.RouteDfinition)
func (p *Plugin) processHandler(rd *ucon.RouteDefinition) error {
if p.swagger == nil {
p.swagger = &Object{}
}
if p.swagger.Paths == nil {
p.swagger.Paths = make(Paths, 0)
}
if p.swagger.Definitions == nil {
p.swagger.Definitions = make(Definitions, 0)
}
item := p.swagger.Paths[rd.PathTemplate.PathTemplate]
if item == nil {
item = &PathItem{}
}
var putOperation func(op *Operation)
// putOperationの設定は省略
op, err := p.extractHandlerInfo(rd)
if err != nil {
return err
}
if op != nil {
p.swagger.Paths[rd.PathTemplate.PathTemplate] = item
putOperation(op)
for _, tsc := range p.typeSchemaMapper {
if !tsc.AllowRef {
continue
}
if tsc.RefName == "" {
return errors.New("Name is required")
}
_, ok := p.swagger.Definitions[tsc.RefName]
if !ok {
p.swagger.Definitions[tsc.RefName] = tsc.Schema
}
}
}
return nil
}
p.swaggerに各種設定を登録していることがわかります。
p.extractHandlerInfo(*ucon.RouteDfinition)を見てみます。
func (p *Plugin) extractHandlerInfo(rd *ucon.RouteDefinition) (*Operation, error) {
// とても長いので省略・・・
}
まとめると、HandleFuncで登録したものがゴニョゴニョ処理されているようでした・・・（多分）
p.swagger.finish()関係は長いのでコード内にインラインで記述していきます。
p.swagger.finish()
func (o *Object) finish() error {
return checkObject(reflect.ValueOf(o))
}
func checkObject(refV reflect.Value) error {
if refV.Kind() == reflect.Ptr {
refV = refV.Elem()
}
var checkNext func(fV reflect.Value) error
// checkNextの設定は省略
for i, numField := 0, refV.NumField(); i < numField; i++ {
sf := refV.Type().Field(i)
fV := refV.Field(i)
swaggerTag := NewTagSwagger(sf.Tag)
// `swagger:",d=hogehoge`のhogehogeがObjectのFieldに設定される
if d := swaggerTag.Default(); d != "" && ucon.IsEmpty(fV) {
err := ucon.SetValueFromString(fV, d)
if err != nil {
return err
}
}
// `swagger:"req"`のようにreqがあり、かつそのFieldが空の場合にエラー
// reqがついたもののうち、Pathsはucon.HandleFuncしていれば自動で登録されている
if swaggerTag.Required() && ucon.IsEmpty(fV) {
return fmt.Errorf("%s is required", sf.Name)
}
// `swagger:",enum=a|b|c"のようにa,b,cがstringであれば処理が走る
if enum := swaggerTag.Enum(); len(enum) != 0 && !ucon.IsEmpty(fV) {
if sf.Type.Kind() != reflect.String {
return fmt.Errorf("unsupported kind: %s", sf.Type.Kind().String())
}
str := fV.String()
found := false
for _, c := range enum {
if c == str {
found = true
break
}
}
if !found {
return fmt.Errorf("invalid value: %s in %s", str, sf.Name)
}
}
// checkNextはarray,slice,struct,mapなど入れ子の構造に使用される
// 特にstructの場合はcheckObject自体が再帰的に実行される
err := checkNext(fV)
if err != nil {
return err
}
}
return nil
}
最終的にHandlerFuncでp.swaggerを返しています。
なお、ucon.Middleware(ResponseMapper())かucon.Orthodox()しないと多分エラーとなるので注意。
さて、ここまで読んで、p.swagger.Swaggerに値が入っていないことに気がついた。
これはどこで定義されているかとsampleに戻ると、swagger.NewHandlerInfoが怪しそうだと気づく。
それでは、見てみましょう・・
plugin.go
// NewHandlerInfo returns new HandlerInfo containing given handler function.
func NewHandlerInfo(handler interface{}) *HandlerInfo {
ucon.CheckFunction(handler)
return &HandlerInfo{
HandlerFunc: handler,
}
}
特に何もなかった。まあいいかｗ
NewHandlerInfoをしないと、おそらくp.extractHandlerInfo(*ucon.RouteDfinition)が機能しないと思われます。