使用自动生成的代码和文档来实现Golang API服务器的方法

在本文中,我想向您介绍如何快速轻松地使用Golang语言及其文档来制作Web服务器。关于实施的方法和工具有哪些


今天,我们将分析以下现成的工具:



昂扬的代码


让我们从swagger.io提供的swagger-api / swagger- codegen开始Swagger Codegen通过为OpenAPI规范(以前称为Swagger)中定义的任何API创建服务器存根和客户端SDK来简化构建过程,您要做的就是实现API。


以下是Swagger文件及其在Swagger编辑器中的视觉外观的示例,在此我们可以为一件事生成实现。


swagger.json
{
  "swagger" : "2.0",
  "info" : {
    "version" : "1.0.0",
    "title" : "Swagger Petstore"
  },
  "host" : "localhost",
  "basePath" : "/v1",
  "tags" : [ {
    "name" : "pet"
  } ],
  "schemes" : [ "https", "http" ],
  "paths" : {
    "/pet" : {
      "post" : {
        "tags" : [ "pet" ],
        "summary" : "Add a new pet to the store",
        "operationId" : "addPet",
        "consumes" : [ "application/json" ],
        "produces" : [ "application/json" ],
        "parameters" : [ {
          "in" : "body",
          "name" : "body",
          "description" : "Pet object that needs to be added to the store",
          "required" : true,
          "schema" : {
            "$ref" : "#/definitions/Pet"
          }
        } ],
        "responses" : {
          "405" : {
            "description" : "Invalid input"
          }
        }
      }
    }
  },
  "definitions" : {
    "Category" : {
      "type" : "object",
      "properties" : {
        "id" : {
          "type" : "integer",
          "format" : "int64"
        },
        "name" : {
          "type" : "string"
        }
      }
    },
    "Tag" : {
      "type" : "object",
      "properties" : {
        "id" : {
          "type" : "integer",
          "format" : "int64"
        },
        "name" : {
          "type" : "string"
        }
      }
    },
    "Pet" : {
      "type" : "object",
      "required" : [ "name", "photoUrls" ],
      "properties" : {
        "id" : {
          "type" : "integer",
          "format" : "int64"
        },
        "category" : {
          "$ref" : "#/definitions/Category"
        },
        "name" : {
          "type" : "string",
          "example" : "doggie"
        },
        "photoUrls" : {
          "type" : "array",
          "items" : {
            "type" : "string"
          }
        },
        "tags" : {
          "type" : "array",
          "items" : {
            "$ref" : "#/definitions/Tag"
          }
        },
        "status" : {
          "type" : "string",
          "description" : "pet status in the store",
          "enum" : [ "available", "pending", "sold" ]
        }
      }
    }
  }
}

Swagger UI中的视觉视图

Swagger UI


从Swagger编辑器导出

Swagger Editor


客户端和服务器具有相同的结构对象。示例文件go-client-generated/model_pet.gogo-server-server-generated/go/model_pet.go


客户端和服务器中的宠物结构模型
/*
 * Swagger Petstore
 *
 * No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen)
 *
 * API version: 1.0.0
 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git)
 */

package swagger

type Pet struct {
    Id int64           `json:"id,omitempty"`
    Category *Category `json:"category,omitempty"`
    Name string        `json:"name"`
    PhotoUrls []string `json:"photoUrls"`
    Tags []Tag         `json:"tags,omitempty"`
    // pet status in the store
    Status string `json:"status,omitempty"`
}

客户端还包含用于发送请求的方法,以及用于处理请求的服务器端点和存根。


客户架构


服务器架构


, . , .


go-swagger


  —  go-swagger/go-swagger. go API- Swagger API: , .


  • Swagger
  • Swagger
  • , jsonschema swagger,
  • swagger go
  • swagger
  • ,


:


$ swagger generate server -f ./swagger.json

 

 


, , . .


go-swagger-service/restapi/configure_swagger_petstore.go. : handler', middleware, , , .


// This file is safe to edit. Once it exists it will not be overwritten

package restapi

import (
    "crypto/tls"
    "net/http"

    errors "github.com/go-openapi/errors"
    runtime "github.com/go-openapi/runtime"
    middleware "github.com/go-openapi/runtime/middleware"

    "go-generator/go-swagger-service/restapi/operations"
    "go-generator/go-swagger-service/restapi/operations/pet"
)

//go:generate swagger generate server --target ../../go-swagger --name SwaggerPetstore --spec ../../swagger.json

func configureFlags(api *operations.SwaggerPetstoreAPI) {
    // api.CommandLineOptionsGroups = []swag.CommandLineOptionsGroup{ ... }
}

func configureAPI(api *operations.SwaggerPetstoreAPI) http.Handler {
    // configure the api here
    api.ServeError = errors.ServeError

    // Set your custom logger if needed. Default one is log.Printf
    // Expected interface func(string, ...interface{})
    //
    // Example:
    // api.Logger = log.Printf

    api.JSONConsumer = runtime.JSONConsumer()

    api.JSONProducer = runtime.JSONProducer()

    if api.PetAddPetHandler == nil {
        api.PetAddPetHandler = pet.AddPetHandlerFunc(func(params pet.AddPetParams) middleware.Responder {
            return middleware.NotImplemented("operation pet.AddPet has not yet been implemented")
        })
    }

    api.ServerShutdown = func() {}

    return setupGlobalMiddleware(api.Serve(setupMiddlewares))
}

// The TLS configuration before HTTPS server starts.
func configureTLS(tlsConfig *tls.Config) {
    // Make all necessary changes to the TLS configuration here.
}

// As soon as server is initialized but not run yet, this function will be called.
// If you need to modify a config, store server instance to stop it individually later, this is the place.
// This function can be called multiple times, depending on the number of serving schemes.
// scheme value will be set accordingly: "http", "https" or "unix"
func configureServer(s *http.Server, scheme, addr string) {
}

// The middleware configuration is for the handler executors. These do not apply to the swagger.json document.
// The middleware executes after routing but before authentication, binding and validation
func setupMiddlewares(handler http.Handler) http.Handler {
    return handler
}

// The middleware configuration happens before anything, this middleware also applies to serving the swagger.json document.
// So this is a good place to plug in a panic handling middleware, logging and metrics
func setupGlobalMiddleware(handler http.Handler) http.Handler {
    return handler
}

. 422 .


swagger . enum, required, type, maximum .


Pet
// Code generated by go-swagger; DO NOT EDIT.

package models

// This file was generated by the swagger tool.
// Editing this file might prove futile when you re-run the swagger generate command

import (
    "encoding/json"
    "strconv"

    strfmt "github.com/go-openapi/strfmt"

    "github.com/go-openapi/errors"
    "github.com/go-openapi/swag"
    "github.com/go-openapi/validate"
)

// Pet pet
// swagger:model Pet
type Pet struct {

    // category
    Category *Category `json:"category,omitempty"`

    // id
    ID int64 `json:"id,omitempty"`

    // name
    // Required: true
    Name *string `json:"name"`

    // photo urls
    // Required: true
    PhotoUrls []string `json:"photoUrls"`

    // pet status in the store
    // Enum: [available pending sold]
    Status string `json:"status,omitempty"`

    // tags
    Tags []*Tag `json:"tags"`
}

// Validate validates this pet
func (m *Pet) Validate(formats strfmt.Registry) error {
    var res []error

    if err := m.validateCategory(formats); err != nil {
        res = append(res, err)
    }

    if err := m.validateName(formats); err != nil {
        res = append(res, err)
    }

    if err := m.validatePhotoUrls(formats); err != nil {
        res = append(res, err)
    }

    if err := m.validateStatus(formats); err != nil {
        res = append(res, err)
    }

    if err := m.validateTags(formats); err != nil {
        res = append(res, err)
    }

    if len(res) > 0 {
        return errors.CompositeValidationError(res...)
    }
    return nil
}

func (m *Pet) validateCategory(formats strfmt.Registry) error {

    if swag.IsZero(m.Category) { // not required
        return nil
    }

    if m.Category != nil {
        if err := m.Category.Validate(formats); err != nil {
            if ve, ok := err.(*errors.Validation); ok {
                return ve.ValidateName("category")
            }
            return err
        }
    }

    return nil
}

func (m *Pet) validateName(formats strfmt.Registry) error {

    if err := validate.Required("name", "body", m.Name); err != nil {
        return err
    }

    return nil
}

func (m *Pet) validatePhotoUrls(formats strfmt.Registry) error {

    if err := validate.Required("photoUrls", "body", m.PhotoUrls); err != nil {
        return err
    }

    return nil
}

var petTypeStatusPropEnum []interface{}

func init() {
    var res []string
    if err := json.Unmarshal([]byte(`["available","pending","sold"]`), &res); err != nil {
        panic(err)
    }
    for _, v := range res {
        petTypeStatusPropEnum = append(petTypeStatusPropEnum, v)
    }
}

const (

    // PetStatusAvailable captures enum value "available"
    PetStatusAvailable string = "available"

    // PetStatusPending captures enum value "pending"
    PetStatusPending string = "pending"

    // PetStatusSold captures enum value "sold"
    PetStatusSold string = "sold"
)

// prop value enum
func (m *Pet) validateStatusEnum(path, location string, value string) error {
    if err := validate.Enum(path, location, value, petTypeStatusPropEnum); err != nil {
        return err
    }
    return nil
}

func (m *Pet) validateStatus(formats strfmt.Registry) error {

    if swag.IsZero(m.Status) { // not required
        return nil
    }

    // value enum
    if err := m.validateStatusEnum("status", "body", m.Status); err != nil {
        return err
    }

    return nil
}

func (m *Pet) validateTags(formats strfmt.Registry) error {

    if swag.IsZero(m.Tags) { // not required
        return nil
    }

    for i := 0; i < len(m.Tags); i++ {
        if swag.IsZero(m.Tags[i]) { // not required
            continue
        }

        if m.Tags[i] != nil {
            if err := m.Tags[i].Validate(formats); err != nil {
                if ve, ok := err.(*errors.Validation); ok {
                    return ve.ValidateName("tags" + "." + strconv.Itoa(i))
                }
                return err
            }
        }

    }

    return nil
}

// MarshalBinary interface implementation
func (m *Pet) MarshalBinary() ([]byte, error) {
    if m == nil {
        return nil, nil
    }
    return swag.WriteJSON(m)
}

// UnmarshalBinary interface implementation
func (m *Pet) UnmarshalBinary(b []byte) error {
    var res Pet
    if err := swag.ReadJSON(b, &res); err != nil {
        return err
    }
    *m = res
    return nil
}


$ run ./go-swagger-service/cmd/swagger-petstore-server/main.go --port 8090


:


$ swagger generate client -f ./swagger.json

 

 


, api-sdk. , , .


// Code generated by go-swagger; DO NOT EDIT.

package pet

// This file was generated by the swagger tool.
// Editing this file might prove futile when you re-run the swagger generate command

import (
    "github.com/go-openapi/runtime"

    strfmt "github.com/go-openapi/strfmt"
)

// New creates a new pet API client.
func New(transport runtime.ClientTransport, formats strfmt.Registry) *Client {
    return &Client{transport: transport, formats: formats}
}

/*
Client for pet API
*/
type Client struct {
    transport runtime.ClientTransport
    formats   strfmt.Registry
}

/*
AddPet adds a new pet to the store
*/
func (a *Client) AddPet(params *AddPetParams) error {
    // TODO: Validate the params before sending
    if params == nil {
        params = NewAddPetParams()
    }

    _, err := a.transport.Submit(&runtime.ClientOperation{
        ID:                 "addPet",
        Method:             "POST",
        PathPattern:        "/pet",
        ProducesMediaTypes: []string{"application/json"},
        ConsumesMediaTypes: []string{"application/json"},
        Schemes:            []string{"http", "https"},
        Params:             params,
        Reader:             &AddPetReader{formats: a.formats},
        Context:            params.Context,
        Client:             params.HTTPClient,
    })
    if err != nil {
        return err
    }
    return nil
}

// SetTransport changes the transport on the client
func (a *Client) SetTransport(transport runtime.ClientTransport) {
    a.transport = transport
}

. Generate a spec from source code.


. , swagger .


grpc-gateway


swagger . grpc-ecosystem/grpc-gateway —   protoc. gRPC -, RESTful JSON API gRPC. gRPC.


HTTP + JSON gRPC. API gRPC RESTful .


grpc-gateway reverse-proxy

grpc-gateway   reverse-proxy


swagger.json protoc-gen-swagger.


. .


$ go install \
    github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway \
    github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger \
    github.com/golang/protobuf/protoc-gen-go

 .proto


protobuf
syntax = "proto3";

import "google/api/annotations.proto";
import "google/protobuf/empty.proto";

package pet;

message AddPetRequest {
    int64 id = 1;
    message Category {
        int64 id = 1;
        string name = 2;
    }
    Category category = 2;
    string name = 3;
    repeated string photo_urls = 4;
    message Tag {
        int64 id = 1;
        string name = 2;
    }
    repeated Tag tags = 5;
    //pet status in the store
    enum Status {
        available = 0;
        pending = 1;
        sold = 2;
    }
    Status status = 6;
}

service PetService {
    rpc AddPet (AddPetRequest) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            post: "/pet"
            body: "*"
        };
    }
}

gRPC stub:


$ protoc -I/usr/local/include -I. \
  -I$GOPATH/src \
  -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
  --go_out=plugins=grpc:. \
  pet.proto

pet.pb.go. reverse-proxy protoc-gen-grpc-gateway:


$ protoc -I/usr/local/include -I. \
  -I$GOPATH/src \
  -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
  --grpc-gateway_out=logtostderr=true:. \
  pet.proto

pet.pb.gw.go . gateway. pet.swagger.json protoc-gen-swagger:


$ protoc -I/usr/local/include -I. \
  -I$GOPATH/src \
  -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
  --swagger_out=logtostderr=true:. \
  pet.proto

PetServiceServer.


// PetServiceServer is the server API for PetService service.
type PetServiceServer interface {
   AddPet(context.Context, *AddPetRequest) (*empty.Empty, error)
}

:


main.go
package pet

import (
    "context"
    "flag"
    "net/http"

    "github.com/golang/glog"
    "github.com/grpc-ecosystem/grpc-gateway/runtime"
    gw "grpc-gateway/pet"
    "grpc-gateway/service"
)

func run() error {
    ctx := context.Background()
    ctx, cancel := context.WithCancel(ctx)
    defer cancel()

    mux := runtime.NewServeMux()
    err := gw.RegisterPetServiceHandlerServer(ctx, mux, &service.PetService{})
    if err != nil {
        return err
    }

    return http.ListenAndServe(":8081", mux)
}

func main() {
    flag.Parse()
    defer glog.Flush()

    if err := run(); err != nil {
        glog.Fatal(err)
    }
}

, . , c grpc-gateway


Swag


Swag Go Swagger 2.0. - Go. swaggo/swag Go ( Swagger UI).


:



Swagger , endpoint'. .


API
// @title Swagger Example API
// @version 1.0
// @description This is a sample server celler server.
// @termsOfService http://swagger.io/terms/

// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host localhost:8080
// @BasePath /api/v1
// @query.collection.format multi

// @securityDefinitions.basic BasicAuth

// @securityDefinitions.apikey ApiKeyAuth
// @in header
// @name Authorization

// @securitydefinitions.oauth2.application OAuth2Application
// @tokenUrl https://example.com/oauth/token
// @scope.write Grants write access
// @scope.admin Grants read and write access to administrative information

// @securitydefinitions.oauth2.implicit OAuth2Implicit
// @authorizationurl https://example.com/oauth/authorize
// @scope.write Grants write access
// @scope.admin Grants read and write access to administrative information

// @securitydefinitions.oauth2.password OAuth2Password
// @tokenUrl https://example.com/oauth/token
// @scope.read Grants read access
// @scope.write Grants write access
// @scope.admin Grants read and write access to administrative information

// @securitydefinitions.oauth2.accessCode OAuth2AccessCode
// @tokenUrl https://example.com/oauth/token
// @authorizationurl https://example.com/oauth/authorize
// @scope.admin Grants read and write access to administrative information

// @x-extension-openapi {"example": "value on a json format"}

func main() {
    // ... 
}

API-
// ShowAccount godoc
// @Summary Show a account
// @Description get string by ID
// @ID get-string-by-int
// @Accept  json
// @Produce  json
// @Param id path int true "Account ID"
// @Success 200 {object} model.Account
// @Header 200 {string} Token "qwerty"
// @Failure 400 {object} httputil.HTTPError
// @Failure 404 {object} httputil.HTTPError
// @Failure 500 {object} httputil.HTTPError
// @Router /accounts/{id} [get]

func (c *ExampleController) ShowAccount(ctx *contex.Context) {
    // ...
}

github.


, , .



现在,我们刚刚通过草率的文档扩展了对可能交互的理解。我们研究了设计代码和为其编写文档的方法。


而且我认为有些人已经选择了合适的方法来实现其新项目的API,或者尝试对当前示例进行分析。


All Articles