You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by GitBox <gi...@apache.org> on 2022/06/20 09:59:02 UTC
[GitHub] [apisix-dashboard] tokers commented on a diff in pull request #2460: refactor: OpenAPI 3 parse and convert
tokers commented on code in PR #2460:
URL: https://github.com/apache/apisix-dashboard/pull/2460#discussion_r901470807
##########
api/internal/handler/data_loader/loader/openapi3/import.go:
##########
@@ -0,0 +1,149 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package openapi3
+
+import (
+ "errors"
+ "fmt"
+ "net/url"
+ "reflect"
+ "strings"
+ "time"
+
+ "github.com/getkin/kin-openapi/openapi3"
+
+ "github.com/apisix/manager-api/internal/core/entity"
+ "github.com/apisix/manager-api/internal/handler/data_loader/loader"
+ "github.com/apisix/manager-api/internal/utils/consts"
+)
+
+func (o Loader) Import(input interface{}) (*loader.DataSets, error) {
+ if input == nil {
+ return nil, errors.New("input is nil")
+ }
+
+ d, ok := input.([]byte)
+ if !ok {
+ return nil, fmt.Errorf("input format error: expected []byte but it is %s", reflect.TypeOf(input).Kind().String())
Review Comment:
Basically, it's a sort of programming faults so I would suggest using `panic` here.
##########
api/internal/handler/data_loader/loader/openapi3/openapi3.go:
##########
@@ -0,0 +1,44 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package openapi3
+
+import (
+ "regexp"
+
+ "github.com/getkin/kin-openapi/openapi3"
+)
+
+type OpenAPISpecFileType string
+
+type Loader struct {
+ // MergeMethod indicates whether to merge routes when multiple HTTP methods are on the same path
+ MergeMethod bool
+ // TaskName indicates the name of current import/export task
+ TaskName string
Review Comment:
I don't see any constraints for this field, we need more details.
##########
api/internal/handler/data_loader/loader/openapi3/import_test.go:
##########
@@ -0,0 +1,109 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package openapi3
+
+import (
+ "io/ioutil"
+ "testing"
+
+ "github.com/stretchr/testify/assert"
+
+ "github.com/apisix/manager-api/internal/core/entity"
+)
+
+var (
+ TestAPI101 = "../../../../../test/testdata/import/Postman-API101.yaml"
+)
+
+// Test API 101 on no MergeMethod mode
+func TestParseAPI101NoMerge(t *testing.T) {
+ fileContent, err := ioutil.ReadFile(TestAPI101)
+ assert.NoError(t, err)
+
+ l := &Loader{MergeMethod: false, TaskName: "test"}
+ data, err := l.Import(fileContent)
+ assert.NoError(t, err)
+
+ assert.Len(t, data.Routes, 5)
+ assert.Len(t, data.Upstreams, 1)
+
+ // Upstream
+ assert.Equal(t, "https", data.Upstreams[0].Scheme)
+ assert.Equal(t, float64(1), data.Upstreams[0].Nodes.(map[string]float64)["api-101.glitch.me"])
+ assert.Equal(t, "test", data.Upstreams[0].Name)
+ assert.Equal(t, "roundrobin", data.Upstreams[0].Type)
+
+ // Route
+ assert.Equal(t, data.Upstreams[0].ID, data.Routes[0].UpstreamID)
+ for _, route := range data.Routes {
+ switch route.Name {
+ case "test_customer_GET":
+ assert.Contains(t, route.Uris, "/customer")
+ assert.Contains(t, route.Methods, "GET")
+ assert.Equal(t, "Get one customer", route.Desc)
+ assert.Equal(t, entity.Status(0), route.Status)
+ case "test_customer/{customer_id}_PUT":
+ assert.Contains(t, route.Uris, "/customer/*")
+ assert.Contains(t, route.Methods, "PUT")
+ assert.Equal(t, "Update customer", route.Desc)
+ assert.Equal(t, entity.Status(0), route.Status)
+ case "test_customer/{customer_id}_DELETE":
+ assert.Contains(t, route.Uris, "/customer/*")
+ assert.Contains(t, route.Methods, "DELETE")
+ assert.Equal(t, "Remove customer", route.Desc)
+ assert.Equal(t, entity.Status(0), route.Status)
+ }
Review Comment:
Should add the `default` arm and run `t.Fail` since a route with bad name exists.
##########
api/internal/handler/data_loader/loader/openapi3/openapi3.go:
##########
@@ -0,0 +1,44 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package openapi3
+
+import (
+ "regexp"
+
+ "github.com/getkin/kin-openapi/openapi3"
+)
+
+type OpenAPISpecFileType string
+
+type Loader struct {
+ // MergeMethod indicates whether to merge routes when multiple HTTP methods are on the same path
+ MergeMethod bool
+ // TaskName indicates the name of current import/export task
+ TaskName string
Review Comment:
How to decide on this field? Two scenarios should be confirmed:
1. Convert the same OAS file twice, with different `TaskName`, then duplicated routes will be created but their functionalities are the same.
2. Convert the two OAS files with the same `TaskName`, and the path and method are the same, will the routes conflict with each other?
##########
api/internal/handler/data_loader/loader/openapi3/import.go:
##########
@@ -0,0 +1,149 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package openapi3
+
+import (
+ "errors"
+ "fmt"
+ "net/url"
+ "reflect"
+ "strings"
+ "time"
+
+ "github.com/getkin/kin-openapi/openapi3"
+
+ "github.com/apisix/manager-api/internal/core/entity"
+ "github.com/apisix/manager-api/internal/handler/data_loader/loader"
+ "github.com/apisix/manager-api/internal/utils/consts"
+)
+
+func (o Loader) Import(input interface{}) (*loader.DataSets, error) {
+ if input == nil {
+ return nil, errors.New("input is nil")
+ }
+
+ d, ok := input.([]byte)
+ if !ok {
+ return nil, fmt.Errorf("input format error: expected []byte but it is %s", reflect.TypeOf(input).Kind().String())
+ }
+
+ // load OAS3 document
+ swagger, err := openapi3.NewSwaggerLoader().LoadSwaggerFromData(d)
+ if err != nil {
+ return nil, err
+ }
+
+ // no paths in OAS3 document
+ if len(swagger.Paths) <= 0 {
+ return nil, consts.ErrImportFile
Review Comment:
This error message is not enough.
Use `errors.Wrap` to carry the context message. See `https://github.com/pkg/errors`.
##########
api/internal/handler/data_loader/loader/openapi3/import.go:
##########
@@ -0,0 +1,180 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package openapi3
+
+import (
+ "errors"
+ "net/url"
+ "strings"
+ "time"
+
+ "github.com/getkin/kin-openapi/openapi3"
+
+ "github.com/apisix/manager-api/internal/core/entity"
+ "github.com/apisix/manager-api/internal/handler/data_loader/loader"
+ "github.com/apisix/manager-api/internal/utils/consts"
+)
+
+func (o Loader) Import(input interface{}) (*loader.DataSets, error) {
+ if input == nil {
+ return nil, errors.New("input is nil")
+ }
+
+ // load OAS3 document
+ swagger, err := openapi3.NewSwaggerLoader().LoadSwaggerFromData(input.([]byte))
+ if err != nil {
+ return nil, err
+ }
+
+ // no paths in OAS3 document
+ if len(swagger.Paths) <= 0 {
+ return nil, consts.ErrImportFile
+ }
+
+ if o.TaskName == "" {
+ o.TaskName = "openapi_" + time.Now().Format("20060102150405")
+ }
+
+ data, err := o.convertToEntities(swagger)
+ if err != nil {
+ return nil, err
+ }
+
+ return data, nil
+}
+
+func (o Loader) convertToEntities(s *openapi3.Swagger) (*loader.DataSets, error) {
+ var (
+ // temporarily save the parsed data
+ data = &loader.DataSets{}
+ // global upstream ID
+ globalUpstreamID = o.TaskName
+ // global uri prefix
+ globalPath = ""
+
+ // authentication plugins supported by APISIX
+ interestedAuthentication = false
+ interestedAuthenticationList = make(map[string]*openapi3.SecuritySchemeRef)
+ )
+
+ // check securitySchemes settings
+ if len(s.Components.SecuritySchemes) > 0 {
+ for name, security := range s.Components.SecuritySchemes {
+ if strings.ToLower(security.Value.Type) == "http" &&
+ strings.ToLower(security.Value.Scheme) == "apikey" {
+ interestedAuthentication = true
+ interestedAuthenticationList[name] = security
+ }
+ }
+ }
+
+ // create upstream when servers field not empty
+ if len(s.Servers) > 0 {
+ var upstream entity.Upstream
+ upstream, globalPath = generateUpstreamByServers(s.Servers, globalUpstreamID)
+ data.Upstreams = append(data.Upstreams, upstream)
+ }
+
+ // each one will correspond to a route
+ for uri, v := range s.Paths {
+ // replace parameter in uri to wildcard
+ realUri := regURIVar.ReplaceAllString(uri, "*")
+ // generate route name
+ routeID := o.TaskName + "_" + strings.NewReplacer("/", "-", "{", "", "}", "").Replace(strings.TrimPrefix(uri, "/"))
+
+ // decide whether to merge multi-method routes based on configuration
+ if o.MergeMethod {
+ // create a single route for each path, merge all methods
+ route := generateBaseRoute(routeID, v.Summary)
+ route.Uris = []string{globalPath + realUri}
+ route.UpstreamID = globalUpstreamID
+ for method := range v.Operations() {
+ route.Methods = append(route.Methods, strings.ToUpper(method))
+ }
+ data.Routes = append(data.Routes, route)
+ } else {
+ // create routes for each method of each path
+ for method, operation := range v.Operations() {
+ subRouteID := routeID + "_" + method
+ route := generateBaseRoute(subRouteID, operation.Summary)
+ route.Uris = []string{globalPath + realUri}
+ route.Methods = []string{strings.ToUpper(method)}
+ route.UpstreamID = globalUpstreamID
+
+ // Processing plugins in non-method merge mode
+ // In method merge mode, different methods may have different authentication
+ // methods, so no plugins are attached to them.
+ if interestedAuthentication &&
+ operation.Security != nil &&
+ len(*operation.Security) > 0 {
+ attachAuthenticationPlugin(route, interestedAuthenticationList, operation.Security)
+ }
+ data.Routes = append(data.Routes, route)
+ }
+ }
+ }
+ return data, nil
+}
+
+// Adding authentication plugins to route based on the security scheme
+// Currently supported: apikey
+func attachAuthenticationPlugin(route entity.Route, refs map[string]*openapi3.SecuritySchemeRef, requirements *openapi3.SecurityRequirements) {
+ for _, requirement := range *requirements {
+ for name := range requirement {
+ // Only add plugins that we can currently handle
+ if _, ok := refs[name]; ok {
+ route.Plugins[authenticationMappings[name]] = map[string]interface{}{}
+ }
+ }
+ }
+}
+
+// Generate APISIX upstream from OpenAPI servers field
+// return upstream and uri prefix
+// Tips: It will use only the first server in servers array
+func generateUpstreamByServers(servers openapi3.Servers, upstreamID string) (entity.Upstream, string) {
+ upstream := entity.Upstream{
+ BaseInfo: entity.BaseInfo{ID: upstreamID},
+ UpstreamDef: entity.UpstreamDef{
+ Name: upstreamID,
+ Type: "roundrobin",
+ },
+ }
+
+ u, err := url.Parse(servers[0].URL)
Review Comment:
It should be the URL exposed by the gateway I guess.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org