cmd/bpa-operator/vendor/k8s.io/kube-openapi/pkg/common/common.go

   1 /*
   2 Copyright 2016 The Kubernetes Authors.
   3
   4 Licensed under the Apache License, Version 2.0 (the "License");
   5 you may not use this file except in compliance with the License.
   6 You may obtain a copy of the License at
   7
   8     http://www.apache.org/licenses/LICENSE-2.0
   9
  10 Unless required by applicable law or agreed to in writing, software
  11 distributed under the License is distributed on an "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 See the License for the specific language governing permissions and
  14 limitations under the License.
  15 */
  16
  17 package common
  18
  19 import (
  20         "net/http"
  21         "strings"
  22
  23         "github.com/emicklei/go-restful"
  24         "github.com/go-openapi/spec"
  25 )
  26
  27 // OpenAPIDefinition describes single type. Normally these definitions are auto-generated using gen-openapi.
  28 type OpenAPIDefinition struct {
  29         Schema       spec.Schema
  30         Dependencies []string
  31 }
  32
  33 type ReferenceCallback func(path string) spec.Ref
  34
  35 // GetOpenAPIDefinitions is collection of all definitions.
  36 type GetOpenAPIDefinitions func(ReferenceCallback) map[string]OpenAPIDefinition
  37
  38 // OpenAPIDefinitionGetter gets openAPI definitions for a given type. If a type implements this interface,
  39 // the definition returned by it will be used, otherwise the auto-generated definitions will be used. See
  40 // GetOpenAPITypeFormat for more information about trade-offs of using this interface or GetOpenAPITypeFormat method when
  41 // possible.
  42 type OpenAPIDefinitionGetter interface {
  43         OpenAPIDefinition() *OpenAPIDefinition
  44 }
  45
  46 type PathHandler interface {
  47         Handle(path string, handler http.Handler)
  48 }
  49
  50 // Config is set of configuration for openAPI spec generation.
  51 type Config struct {
  52         // List of supported protocols such as https, http, etc.
  53         ProtocolList []string
  54
  55         // Info is general information about the API.
  56         Info *spec.Info
  57
  58         // DefaultResponse will be used if an operation does not have any responses listed. It
  59         // will show up as ... "responses" : {"default" : $DefaultResponse} in the spec.
  60         DefaultResponse *spec.Response
  61
  62         // ResponseDefinitions will be added to "responses" under the top-level swagger object. This is an object
  63         // that holds responses definitions that can be used across operations. This property does not define
  64         // global responses for all operations. For more info please refer:
  65         //     https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#fixed-fields
  66         ResponseDefinitions map[string]spec.Response
  67
  68         // CommonResponses will be added as a response to all operation specs. This is a good place to add common
  69         // responses such as authorization failed.
  70         CommonResponses map[int]spec.Response
  71
  72         // List of webservice's path prefixes to ignore
  73         IgnorePrefixes []string
  74
  75         // OpenAPIDefinitions should provide definition for all models used by routes. Failure to provide this map
  76         // or any of the models will result in spec generation failure.
  77         GetDefinitions GetOpenAPIDefinitions
  78
  79         // GetOperationIDAndTags returns operation id and tags for a restful route. It is an optional function to customize operation IDs.
  80         GetOperationIDAndTags func(r *restful.Route) (string, []string, error)
  81
  82         // GetDefinitionName returns a friendly name for a definition base on the serving path. parameter `name` is the full name of the definition.
  83         // It is an optional function to customize model names.
  84         GetDefinitionName func(name string) (string, spec.Extensions)
  85
  86         // PostProcessSpec runs after the spec is ready to serve. It allows a final modification to the spec before serving.
  87         PostProcessSpec func(*spec.Swagger) (*spec.Swagger, error)
  88
  89         // SecurityDefinitions is list of all security definitions for OpenAPI service. If this is not nil, the user of config
  90         // is responsible to provide DefaultSecurity and (maybe) add unauthorized response to CommonResponses.
  91         SecurityDefinitions *spec.SecurityDefinitions
  92
  93         // DefaultSecurity for all operations. This will pass as spec.SwaggerProps.Security to OpenAPI.
  94         // For most cases, this will be list of acceptable definitions in SecurityDefinitions.
  95         DefaultSecurity []map[string][]string
  96 }
  97
  98 var schemaTypeFormatMap = map[string][]string{
  99         "uint":        {"integer", "int32"},
 100         "uint8":       {"integer", "byte"},
 101         "uint16":      {"integer", "int32"},
 102         "uint32":      {"integer", "int64"},
 103         "uint64":      {"integer", "int64"},
 104         "int":         {"integer", "int32"},
 105         "int8":        {"integer", "byte"},
 106         "int16":       {"integer", "int32"},
 107         "int32":       {"integer", "int32"},
 108         "int64":       {"integer", "int64"},
 109         "byte":        {"integer", "byte"},
 110         "float64":     {"number", "double"},
 111         "float32":     {"number", "float"},
 112         "bool":        {"boolean", ""},
 113         "time.Time":   {"string", "date-time"},
 114         "string":      {"string", ""},
 115         "integer":     {"integer", ""},
 116         "number":      {"number", ""},
 117         "boolean":     {"boolean", ""},
 118         "[]byte":      {"string", "byte"}, // base64 encoded characters
 119         "interface{}": {"object", ""},
 120 }
 121
 122 // This function is a reference for converting go (or any custom type) to a simple open API type,format pair. There are
 123 // two ways to customize spec for a type. If you add it here, a type will be converted to a simple type and the type
 124 // comment (the comment that is added before type definition) will be lost. The spec will still have the property
 125 // comment. The second way is to implement OpenAPIDefinitionGetter interface. That function can customize the spec (so
 126 // the spec does not need to be simple type,format) or can even return a simple type,format (e.g. IntOrString). For simple
 127 // type formats, the benefit of adding OpenAPIDefinitionGetter interface is to keep both type and property documentation.
 128 // Example:
 129 // type Sample struct {
 130 //      ...
 131 //      // port of the server
 132 //      port IntOrString
 133 //      ...
 134 // }
 135 // // IntOrString documentation...
 136 // type IntOrString { ... }
 137 //
 138 // Adding IntOrString to this function:
 139 // "port" : {
 140 //           format:      "string",
 141 //           type:        "int-or-string",
 142 //           Description: "port of the server"
 143 // }
 144 //
 145 // Implement OpenAPIDefinitionGetter for IntOrString:
 146 //
 147 // "port" : {
 148 //           $Ref:    "#/definitions/IntOrString"
 149 //           Description: "port of the server"
 150 // }
 151 // ...
 152 // definitions:
 153 // {
 154 //           "IntOrString": {
 155 //                     format:      "string",
 156 //                     type:        "int-or-string",
 157 //                     Description: "IntOrString documentation..."    // new
 158 //           }
 159 // }
 160 //
 161 func GetOpenAPITypeFormat(typeName string) (string, string) {
 162         mapped, ok := schemaTypeFormatMap[typeName]
 163         if !ok {
 164                 return "", ""
 165         }
 166         return mapped[0], mapped[1]
 167 }
 168
 169 func EscapeJsonPointer(p string) string {
 170         // Escaping reference name using rfc6901
 171         p = strings.Replace(p, "~", "~0", -1)
 172         p = strings.Replace(p, "/", "~1", -1)
 173         return p
 174 }