github.com/kaisawind/go-swagger@v0.19.0/docs/use/server.md (about)

     1  # Use the generated server
     2  
     3  The generated server serves the API but the default implementation returns 501 Not implemented for everything. Let's
     4  look into using the generated code.
     5  
     6  Go swagger primarily deals with HTTP and originally only supports the stdlib `net/http` interface. A typical HTTP
     7  request expects a response.  This is reflected in go-swagger where a handler is typically defined as a function of
     8  input parameters to a responder.
     9  
    10  ```go
    11  type ListTravelsHandler interface {
    12  	Handle(ListTravelsParams) middleware.Responder
    13  }
    14  ```
    15  
    16  The signature of this handler is one of 2 possible variations. When a handler doesn't use authentication then a handler
    17  interface consists out of input parameters and a responder.
    18  
    19  ```go
    20  type AddOneAuthenticatedHandler interface {
    21  	Handle(AddOneParams, interface{}) middleware.Responder
    22  }
    23  ```
    24  
    25  When a handler does use authentication then the second argument to the handler function represents the security
    26  principal for your application. You can specify the type name for this principal at generation time by specifying the
    27  -P or --principal flag.
    28  
    29  ```
    30  swagger generate server -P models.User
    31  swagger generate client -P models.User
    32  ```
    33  
    34  See the full list of available options [for server](../generate/server.md) and [for client](../generate/client.md).
    35  
    36  When you would execute the generate step with that parameter for the security principal then the
    37  AddOneAuthenticatedHandler would look a bit like this:
    38  
    39  ```go
    40  type AddOneAuthenticatedHandler interface {
    41  	Handle(AddOneParams, *models.User) middleware.Responder
    42  }
    43  ```
    44  
    45  ## Implement handlers
    46  
    47  A handler is an interface/contract that defines a statically typed representation of the input and output parameters of
    48  an operation on your API.
    49  The tool generates handlers that are stubbed with a NotImplemented response when you first generate the server.
    50  
    51  ### The `not implemented` handler
    52  
    53  The not implemented handler is actually a not implemented responder, it returns a responder that will always respond
    54  with status code 501 and a message that lets people know it's not the fault of the client that things don't work.
    55  
    56  ```go
    57  middleware.NotImplemented("operation todos.AddOne has not yet been implemented")
    58  ```
    59  
    60  ### Your own code
    61  
    62  Each HTTP request expects a response of some sort, this response might have no data but it's a response none the less.
    63  
    64  Every incoming request is described as a bunch of input parameters which have been validated prior to calling the
    65  handler. So whenever your code is executed, the input parameters are guaranteed to be valid according to what the
    66  swagger specification prescribes.
    67  
    68  All the input parameters have been validated, and the request has been authenticated should it have triggered
    69  authentication.
    70  
    71  You probably want to return something a bit more useful to the users of your API than a not implemented response.
    72  
    73  A possible implementation of the `ListTravelsHandler` interface might look like this:
    74  
    75  ```go
    76  type PublicListTravelsOK struct {
    77    Body []models.Travel
    78  }
    79  func (m *PublicListTravelsOK) WriteResponse(rw http.ResponseWriter, producer httpkit.Producer){
    80    // generated code here
    81  }
    82  
    83  type PublicListTravelsError struct {
    84    Body models.Error
    85  }
    86  func (m *PublicListTravelsOK) WriteResponse(rw http.ResponseWriter, producer httpkit.Producer){
    87    // generated code here
    88  }
    89  
    90  type PublicListTravelsHandler struct {
    91    db interface {
    92      FetchTravels(*PublicListTravelsParams) ([]models.Travel, error)
    93    }
    94  }
    95  
    96  func (m *PublicListTravelsHandler) Handle(params ListTravelsParams) middleware.Responder {
    97    travels, err := m.db.FetchTravels(&params)
    98    if err != nil {
    99      return &PublicListTravelsError{Body: models.Error{Message: err.Error()}}
   100    }
   101    return &PublicListTravelsOK{Body: travels}
   102  }
   103  ```
   104  
   105  In the example above we have a handler implementation with a hypothetical database fetch interface. When the handle
   106  method is executed there are 2 possible responses for the provided parameters. There can either be an error in which
   107  case the PublicListTravelsError will be returned, otherwise the PublicListTravelsOK will be returned.
   108  
   109  The code generator has written the remaining code to render that response with the headers etc.
   110