go-swagger-tutorial/docs/Part_02.md

Review of Part One

In Part One of Go-Swagger, we generated a on OpenAPI 2.0 server with REST endpoints. The server builds and responds to queries, but every valid query ends with "This feature has not yet been implemented."

It's time to implement the feature.

I want to emphasize that with Go Swagger there is only one generated file you need to touch. Since our project is named timeofday, the file will be named restapi/configure_timeofday.go. Our first step will be to break those "not implemented" functions out into their own Go package. That package will be our business logic. The configure file and the business logic package will be the only things we change.

A reminder: The final source code for this project is available on Github, however Parts One & Two deal with the most common implementation, a server with hard-coded default values. For these chapters, please consult that specific version of the code.

Break out the business logic

Create a new folder in your project root and call it timeofday.

Open up your editor and find the file restapi/configure_timeofday.go. In your swagger.yml file you created two endpoints and gave them each an operationId: TimePost and TimeGet. Inside configure_timeofday.go, you should find two corresponding assignments in the function configureAPI(): TimeGetHandlerFunc and TimePostHandlerFunc. Inside those function calls, you'll find anonymous functions.

I want you to take those anonymous functions, cut them out, and paste them into a new file inside the timeofday/ folder. You will also have to create a package name and import any packages being used. Now your file, which I've called timeofday/handlers.go, looks like this (note that you'll have to change your import paths as you're probably not elfsternberg. Heck, I'm probably not elfsternberg):

<<handlers.go before implementation>>=
package timeofday

import(
  "github.com/go-openapi/runtime/middleware"
  "github.com/elfsternberg/timeofday/restapi/operations"
)

func GetTime(params operations.TimeGetParams) middleware.Responder {
  return middleware.NotImplemented("operation .TimeGet has not yet been implemented")
}

func PostTime(params operations.TimePostParams) middleware.Responder {
  return middleware.NotImplemented("operation .TimePost has not yet been implemented")
}
@

And now go back to restapi/configure_timeofday.go, add github.com/elfsternberg/timeofday/clock to the imports, and change the handler lines to look like this:

<<configuration lines before implementation>>=
	api.TimeGetHandler = operations.TimeGetHandlerFunc(timeofday.GetTime)
	api.TimePostHandler = operations.TimePostHandlerFunc(timeofday.PostTime)
@

Implementation

Believe it or not, you've now done everything you need to do except the business logic. We're going to honor the point of OpenAPI and the `// DO NOT EDIT`` comments, and not modify anything exceept the contents of our handler.

To understand our code, though, we're going to have to read some of those files. Let's go look at /models. In here, you'll find the schemas you outlined in the swagger.yml file turned into source code. If you open one, like many files generated by Swagger, you'll see it reads // DO NOT EDIT. But then there's that function there, Validate(). What if you want to do advanced validation for custom patterns or inter-field relations not covered by Swagger's validators?

Well, you'll have to edit this file. And figure out how to live with it. We're not going to do that here. This exercise is about not editing those files. But we can see, for example, that the Timezone object has a field, Timezone.Timezone, which is a string, and which has to be at least three bytes long.

The other thing you'll have to look at is the restapi/operations folder. In here you'll find GET and POST operations, the parameters they accept, the responses they deliver, and lots of functions only Swagger cares about. But there are a few we care about.

Here's how we craft the GET response. Inside handlers.go, you're going to need to extract the requested timezone, get the time of day, and then return either a success message or an error message. Looking in the operations files, there are a methods for good and bad returns, as we described in the swagger file.

<<gettime implementation>>=
func GetTime(params operations.TimeGetParams) middleware.Responder {
	var tz *string = nil

	if (params.Timezone != nil) {
		tz = params.Timezone
	}

	thetime, err := getTimeOfDay(params.Timezone)

@

The first thing to notice here is the params field: we're getting a customized, tightly bound object from the server. There's no hope of abstraction here. The next is that we made the Timezone input optional, so here we have to check if it's nil or not. if it isn't, we need to set it. We do this here because we need to cast params.Timezone into a pointer to a string, because Go is weird about types.

We then call a (thus far undefined) function called getTimeOfDay.

Let's deal with the error case:

<<gettime implementation>>=
	if err != nil {
		return operations.NewTimeGetNotFound().WithPayload(
			&models.ErrorResponse {
				int32(operations.TimeGetNotFoundCode),
				swag.String(fmt.Sprintf("%s", err)),
			})
	}
@

That's a lot of references. We have a model, an operation, and what's that "swag" thing? In order to satisfy Swagger's strictness, we use only what Swagger offers: for our 404 case, we didn't find the timezone requested, so we're returning the ErrorResponse model populated with a numeric code and a string, extracted via fmt, from the err returned from our time function. The 404 case for get is called, yes, NewClockGetNotFound, and then WithPayload() decorates the body of the response with content.

The good path is similar:

<<gettime implementation>>=
	return operations.NewClockGetOK().WithPayload(
		&models.Timeofday{
			Timeofday: *thetime,
		})
}
@

Now might be a good time to go look in models/ and /restapi/options, to see what's available to you. You'll need to do so anyway, because unless you go to the git repository and cheat, I'm going to leave it up to you to implement the PostTime().

There's still one thing missing, though: the actual time of day. We'll need a default, and we'll need to test to see if the default is needed. The implementation is straightforward:

<<timeofday function>>=
func getTimeOfDay(tz *string) (*string, error) {
        defaultTZ := "UTC"

        t := time.Now()
        if tz == nil {
                tz = &defaultTZ
        }

        utc, err := time.LoadLocation(*tz)
        if err != nil {
                return nil, errors.New(fmt.Sprintf("Time zone not found: %s", *tz))
        }

        thetime := t.In(utc).String()
        return &thetime, nil
}
@

Now, if you've written everything correctly, and the compiler admits that you have (or you can cheat and download the 0.2.0-tagged version from the the repo), you'll be able to build, compile, and run the server, and see it working:

$ go build ./cmd/timeofday-server/
$ ./timeofday-server --port=8080

And then test it with curl:

$ curl 'http://localhost:8020/timeofday/v1/time'
{"timeofday":"2018-03-31 02:57:48.814683375 +0000 UTC"}
$ curl 'http://localhost:8020/timeofday/v1/time?timezone=UTC'
{"timeofday":"2018-03-31 02:57:50.443200906 +0000 UTC"}
$ curl 'http://localhost:8020/timeofday/v1/time?timezone=America/Los_Angeles'
{"timeofday":"2018-03-30 19:57:59.886650128 -0700 PDT"}

And that's the end of Part 2. If you've gotten this far, congratulations! Just a reminder, a working version of this server is available under the "0.2.0" tag at the repo.

On to Part 3