OpenAPI 3.0 Standards

OpenAPI 3.0 standards is a Go module dedicated to standardizing our duplicate code related to responses, endpoints, and models. See https://stocktwits.stoplight.io/docs/openapi-standards/ for endpoints and types

Support

Currently this standard library only supports Echo, but is expandable to other server types.

OpenAPI 3.0 Spec

Editing

If we want to update the paths, models, or responses simply edit the project in Stoplight and push a PR https://stocktwits.stoplight.io/studio/openapi-standards.

Updating

From the root of the repo run the following.

# Update the types, endpoints, and interfaces across all Go server types
go generate ./...

Echo Server

The Echo standard server has a few components. There is the following

• Middleware
• Server Interface
• Response Types
• Swagger Spec

Echo Middleware

For the Middleware you simply add it as you would any echo powered middleware.

	e := echo.New()
	// Log requests
	e.Use(standardechomiddleware.Logger())

Echo Server Interface

The Echo server interface creates the interface between the system and the standard, and often required, routes. You simply need to have your server struct implment the different handlers, or simply call the prewritten handlers. Once this is implemented you simply write the following.

    // Our implementation of standardechoroutes.ServerInterface
    server := newAPIServer()
    standardSwagger, err := api.GetSwagger()
    if err != nil {
        handleError(err)
    }

	// This is how you set up a basic Echo router
	e := echo.New()

	// Use our validation middleware to check all requests against the
	// OpenAPI schema.
	e.Use(middleware.OapiRequestValidator(standardSwagger))

	// We now register our server above as the handler for the healthcheck and other standard handlers
	standardechoroutes.RegisterHandlers(e, server)

Echo Response Types

When required simply respond with the known type as you would with any other struct.

Echo Swagger Spec

With Echo the swagger spec handles input checking, to implement check the server interface implementation. You simply load it and then attach it using a middleware. Use standardechoroutes.CombineOpenAPISpecs to combine two swagger definitions together.

    standardSwagger, err := api.GetSwagger()
    if err != nil {
        handleError(err)
    }

    e := echo.New()
    e.Use(middleware.OapiRequestValidator(standardSwagger))