Swaggest REST

https://github.com/swaggest/rest
Admin
Swaggest REST is a Go module for building REST services with Clean Architecture, featuring automatic...
Tokens:7,060
Snippets:29
Trust Score:8.1
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Run Basic Example in Go

Source: https://github.com/swaggest/rest/blob/master/_examples/basic/README.md

This snippet shows the command-line steps to set up a Go project, download the basic example from swaggest/rest, run it, and then clean up the project files. It's a self-contained way to quickly test the library's functionality.

```bash
cd /tmp;go mod init foo;go get -u github.com/swaggest/rest/_examples/basic;go run github.com/swaggest/rest/_examples/basic;rm go.mod;rm go.sum
```

--------------------------------

### Basic REST API Example

Source: https://github.com/swaggest/rest/blob/master/README.md

A complete example of a REST API using swaggest/rest. It includes service initialization, middleware setup (gzip), defining input and output structures with schema constraints, implementing a use case interactor, routing, and serving Swagger UI.

```go
package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"net/http"
	"time"

	"github.com/swaggest/openapi-go/openapi31"
	"github.com/swaggest/rest/response/gzip"
	"github.com/swaggest/rest/web"
	swgui "github.com/swaggest/swgui/v5emb"
	"github.com/swaggest/usecase"
	"github.com/swaggest/usecase/status"
)

func main() {
	s := web.NewService(openapi31.NewReflector())

	// Init API documentation schema.
	s.OpenAPISchema().SetTitle("Basic Example")
	s.OpenAPISchema().SetDescription("This app showcases a trivial REST API.")
	s.OpenAPISchema().SetVersion("v1.2.3")

	// Setup middlewares.
	s.Wrap(
		gzip.Middleware, // Response compression with support for direct gzip pass through.
	)

	// Declare input port type.
	type helloInput struct {
		Locale string `query:"locale" default:"en-US" pattern:"^[a-z]{2}-[A-Z]{2}$" enum:"ru-RU,en-US"
		Name   string `path:"name" minLength:"3"` // Field tags define parameter location and JSON schema constraints.

		// Field tags of unnamed fields are applied to parent schema.
		// they are optional and can be used to disallow unknown parameters.
		// For non-body params, name tag must be provided explicitly.
		// E.g. here no unknown `query` and `cookie` parameters allowed,
		// unknown `header` params are ok.
		_ struct{} `query:"_" cookie:"_" additionalProperties:"false"`
	}

	// Declare output port type.
	type helloOutput struct {
		Now     time.Time `header:"X-Now" json:"-"`
		Message string    `json:"message"`
	}

	messages := map[string]string{
		"en-US": "Hello, %s!",
		"ru-RU": "Привет, %s!",
	}

	// Create use case interactor with references to input/output types and interaction function.
	u := usecase.NewInteractor(func(ctx context.Context, input helloInput, output *helloOutput) error {
		msg, available := messages[input.Locale]
		if !available {
			return status.Wrap(errors.New("unknown locale"), status.InvalidArgument)
		}

		output.Message = fmt.Sprintf(msg, input.Name)
		output.Now = time.Now()

		return nil
	})

	// Describe use case interactor.
	u.SetTitle("Greeter")
	u.SetDescription("Greeter greets you.")

	u.SetExpectedErrors(status.InvalidArgument)

	// Add use case handler to router.
	s.Get("/hello/{name}", u)

	// Swagger UI endpoint at /docs.
	s.Docs("/docs", swgui.New)

	// Start server.
	log.Println("http://localhost:8011/docs")
	if err := http.ListenAndServe("localhost:8011", s); err != nil {
		log.Fatal(err)
	}
}

```

--------------------------------

### Handler Setup

Source: https://github.com/swaggest/rest/blob/master/README.md

Demonstrates the basic setup of a use case handler within a router. It shows how to associate an HTTP method and path with a use case interactor using `nethttp.NewHandler`.

```go
// Add use case handler to router.
r.Method(http.MethodGet, "/hello/{name}", nethttp.NewHandler(u))
```

--------------------------------

### Access Documentation URL

Source: https://github.com/swaggest/rest/blob/master/_examples/basic/README.md

After running the basic example, this output indicates the URL where the generated API documentation can be accessed via a web browser.

```text
2020/12/02 12:27:18 http://localhost:8011/docs
```

--------------------------------

### Router Setup with Middlewares

Source: https://github.com/swaggest/rest/blob/master/ADVANCED.md

Details the setup of a REST router using `go-chi/chi` and `swaggest/rest`. It outlines the required middlewares for documentation, request decoding, and response encoding, along with optional middlewares for validation and compression. The example demonstrates how to create a wrapper, apply middlewares, and register the Swagger UI endpoint.

```go
package main

import (
	"net/http"

	"github.com/go-chi/chi"
	"github.com/swaggest/jsonschema/jsonschema"
	"github.com/swaggest/rest"
	"github.com/swaggest/rest/gzip"
	"github.com/swaggest/rest/nethttp"
	"github.com/swaggest/rest/openapi"
	"github.com/swaggest/rest/request"
	"github.com/swaggest/rest/response"
	"github.com/swaggest/rest/web/v3cdn"
	"github.com/swaggest/usecase/middleware"
	"github.com/swaggest/openapi-go/openapi31"
)

func main() {
	// Init API documentation schema.
	apiSchema := openapi.NewCollector(openapi31.NewReflector())
	apiSchema.SpecSchema().SetTitle("Basic Example")
	apiSchema.SpecSchema().SetDescription("This app showcases a trivial REST API.")
	apiSchema.SpecSchema().SetVersion("v1.2.3")

	// Setup request decoder and validator.
	validatorFactory := jsonschema.NewFactory(apiSchema, apiSchema)
	decoderFactory := request.NewDecoderFactory()
	decoderFactory.SetDecoderFunc(rest.ParamInPath, chirouter.PathToURLValues)

	// Create router.
	r := chirouter.NewWrapper(chi.NewRouter())

	// Setup middlewares.
	r.Use(
		middleware.Recoverer,                          // Panic recovery.
		nethttp.OpenAPIMiddleware(apiSchema),          // Documentation collector.
		request.DecoderMiddleware(decoderFactory),     // Request decoder setup.
		request.ValidatorMiddleware(validatorFactory), // Request validator setup.
		response.EncoderMiddleware,                    // Response encoder setup.
		gzip.Middleware,                               // Response compression with support for direct gzip pass through.
	)

	// Register Swagger UI to serve documentation at /docs.
	r.Method(http.MethodGet, "/docs/openapi.json", apiSchema)
	r.Mount("/docs", v3cdn.NewHandler(apiSchema.Reflector().Spec.Info.Title,
		"/docs/openapi.json", "/docs"))

	// http.ListenAndServe(":8080", r)
}

// Dummy chirouter for compilation
// In a real scenario, this would be imported from "github.com/swaggest/rest/chirouter"
var chirouter = struct {
	PathToURLValues func(r *http.Request, p string) map[string]string
}{
	PathToURLValues: func(r *http.Request, p string) map[string]string {
		return nil
	},
}

```

--------------------------------

### Initializing a Web Service

Source: https://github.com/swaggest/rest/blob/master/README.md

Shows the initialization of a web service using `web.NewService`, including OpenAPI configuration, middleware setup, and mounting use cases.

```go
// Service initializes router with required middlewares.
service := web.NewService(openapi31.NewReflector())

// It allows OpenAPI configuration.
service.OpenAPISchema().SetTitle("Albums API")
service.OpenAPISchema().SetDescription("This service provides API to manage albums.")
service.OpenAPISchema().SetVersion("v1.0.0")

// Additional middlewares can be added.
service.Use(
    middleware.StripSlashes,

    // cors.AllowAll().Handler, // "github.com/rs/cors", 3rd-party CORS middleware can also be configured here.
)

// Use cases can be mounted using short syntax .<Method>(...).service.Post("/albums", postAlbums(), nethttp.SuccessStatus(http.StatusCreated))

log.Println("Starting service at http://localhost:8080")

if err := http.ListenAndServe("localhost:8080", service); err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Update Router Dependency Import

Source: https://github.com/swaggest/rest/blob/master/UPGRADE.md

Details the required import path change for the router dependency due to an upgrade. Users must update their import statements to reflect the new module path.

```go
import (
	"github.com/go-chi/chi/v5"
)
```

--------------------------------

### API Schema Collector Initialization

Source: https://github.com/swaggest/rest/blob/master/ADVANCED.md

Illustrates the initialization of an OpenAPI schema collector using `openapi-go`. This process involves creating a reflector and setting basic API metadata such as title, description, and version. This schema is crucial for generating OpenAPI documentation.

```go
package main

import (
	"github.com/swaggest/openapi-go/openapi31"
	"github.com/swaggest/rest/openapi"
)

func main() {
	// Init API documentation schema.
	apiSchema := openapi.NewCollector(openapi31.NewReflector())
	apiSchema.SpecSchema().SetTitle("Basic Example")
	apiSchema.SpecSchema().SetDescription("This app showcases a trivial REST API.")
	apiSchema.SpecSchema().SetVersion("v1.2.3")
}

```

--------------------------------

### Create Modular Use Case Interactor

Source: https://github.com/swaggest/rest/blob/master/ADVANCED.md

Demonstrates how to create a modular use case interactor by embedding traits in a struct. This allows for flexible composition of use case functionalities, skipping components like `usecase.WithInput` if not needed. It also shows how to set the title, description, input, output, and the core interaction logic.

```go
package main

import (
	"context"
	"net/http"

	"github.com/swaggest/usecase"
	"github.com/swaggest/usecase/nethttp"
)

type helloInput struct {
	Name string `path:"name"`
}

type helloOutput struct {
	Greeting string `json:"greeting,omitempty"`
}

func main() {
	// Create use case interactor.
	u := struct {
		usecase.Info
		usecase.Interactor
		usecase.WithInput
		usecase.WithOutput
	}{}

	// Describe use case interactor.
	u.SetTitle("Greeter")
	u.SetDescription("Greeter greets you.")
	u.Input = new(helloInput)
	u.Output = new(helloOutput)
	u.Interactor = usecase.Interact(func(ctx context.Context, input, output interface{}) error {
		// Do something about input to prepare output.
		output.(*helloOutput).Greeting = "Hello, " + input.(*helloInput).Name
		return nil
	})

	// Add use case handler to router.
	r := nethttp.NewRouter()
	r.Method(http.MethodGet, "/hello/{name}", nethttp.NewHandler(u))

	// http.ListenAndServe(":8080", r)
}

```

--------------------------------

### Adding Use Case Handler with Custom Input Mapping

Source: https://github.com/swaggest/rest/blob/master/README.md

Demonstrates how to add a use case handler to a router with a custom input mapping. It specifies the HTTP method, path, and uses `nethttp.NewHandler` with `nethttp.RequestMapping` to define the input structure and parameter mapping.

```go
// Add use case handler with custom input mapping to router.
r.Method(http.MethodGet, "/hello/{name}", nethttp.NewHandler(u,
    nethttp.RequestMapping(new(struct {
       Locale string `query:"locale"`
       Name   string `path:"name"` // Field tags define parameter location and JSON schema constraints.
    })),
))
```

--------------------------------

### Creating a Use Case Interactor

Source: https://github.com/swaggest/rest/blob/master/README.md

Illustrates the creation of a use case interactor, which decouples business logic from HTTP transport. It defines input and output ports and the interaction function.

```go
// Create use case interactor with references to input/output types and interaction function.
u := usecase.NewInteractor(func(ctx context.Context, input helloInput, output *helloOutput) error {
    msg, available := messages[input.Locale]
    if !available {
        return status.Wrap(errors.New("unknown locale"), status.InvalidArgument)
    }

    output.Message = fmt.Sprintf(msg, input.Name)
    output.Now = time.Now()

    return nil
})
```

--------------------------------

### OpenAPI 3.0/3.1 Documentation Generation

Source: https://github.com/swaggest/rest/blob/master/README.md

Generates type-safe OpenAPI 3.0/3.1 documentation using github.com/swaggest/openapi-go. This feature ensures a single source of truth for API documentation and endpoint interfaces.

```go
import (
	"github.com/swaggest/openapi-go"
)

// Example of generating OpenAPI documentation
func GenerateOpenAPIDocs() {
	// ... implementation details ...
}
```

--------------------------------

### Manual Request Loading in Go

Source: https://github.com/swaggest/rest/blob/master/README.md

Demonstrates how to implement a manual request loader for input types in Go. This method bypasses automatic decoding and validation, allowing for custom handling of HTTP requests to improve performance. It specifically shows how to extract a header value from an incoming HTTP request.

```go
func (i *myInput) LoadFromHTTPRequest(r *http.Request) (err error) {
	i.Header = r.Header.Get("X-Header")

	return nil
}
```

--------------------------------

### Response Encoder with Custom Header Mapping

Source: https://github.com/swaggest/rest/blob/master/README.md

Demonstrates how to map specific output fields to HTTP headers when initializing a handler, allowing for explicit separation of concerns.

```go
// Declare output port type.
type helloOutput struct {
    Now     time.Time `json:"-"`
    Message string    `json:"message"`
}

// Add use case handler with custom output headers mapping to router.
r.Method(http.MethodGet, "/hello/{name}", nethttp.NewHandler(u,
    nethttp.ResponseHeaderMapping(new(struct {
        Now     time.Time `header:"X-Now"`
    })),
))
```

--------------------------------

### Go Struct for Request Decoding with Field Tags

Source: https://github.com/swaggest/rest/blob/master/README.md

Defines an input port structure for a 'hello' request using Go struct tags. Tags specify parameter location (query, path), default values, validation patterns, enums, and minimum length. It also demonstrates how to disallow unknown parameters.

```go
type helloInput struct {
    Locale string `query:"locale" default:"en-US" pattern:"^[a-z]{2}-[A-Z]{2}$" enum:"ru-RU,en-US"`
    Name   string `path:"name" minLength:"3"` // Field tags define parameter location and JSON schema constraints.

    // Field tags of unnamed fields are applied to parent schema, 
	// they are optional and can be used to disallow unknown parameters.
    // For non-body params, name tag must be provided explicitly.
    // E.g. here no unknown `query` and `cookie` parameters allowed,
    // unknown `header` params are ok.
    _ struct{} `query:"_" cookie:"_" additionalProperties:"false"`
}
```

--------------------------------

### Response Control Interfaces

Source: https://github.com/swaggest/rest/blob/master/ADVANCED.md

Outlines interfaces for customizing response handling. `NoContent` determines if a 204 status should be returned. `SetupResponseHeader` allows modification of response headers. `ETag` retrieves the ETag header value. `SetWriter` enables full control over the `http.ResponseWriter`. `HTTPStatus` and `ExpectedHTTPStatuses` define success status codes for documentation.

```APIDOC
Response Control:

NoContent() bool
  - Controls whether status 204 should be used in response to the current request.
  - Returns: true if 204 status should be used, false otherwise.

SetupResponseHeader(h http.Header)
  - Provides access to response headers of the current request for modification.
  - Parameters:
    - h: http.Header object to modify.

ETag() string
  - Returns the ETag response header value for the current request.
  - Returns: The ETag string.

SetWriter(w io.Writer)
  - Takes full control of http.ResponseWriter.
  - Prevents automated response handling.
  - Parameters:
    - w: The io.Writer to use for the response.

HTTPStatus() int
  - Declares the successful HTTP status for all requests.
  - Returns: The HTTP status code.

ExpectedHTTPStatuses() []int
  - Declares additional HTTP statuses for all requests.
  - Used only for documentation purposes.
  - Returns: A slice of integer HTTP status codes.
```

--------------------------------

### JSON Schema Constraints and Customizations

Source: https://github.com/swaggest/rest/blob/master/README.md

Explains that additional field tags in Go structs can describe JSON schema constraints. It references the `jsonschema-go` documentation for detailed information and mentions the possibility of implementing `jsonschema-go` interfaces for more advanced schema customizations.

```APIDOC
Additional field tags describe JSON schema constraints, please check
[documentation](https://pkg.go.dev/github.com/swaggest/jsonschema-go#Reflector.Reflect).

More schema customizations are possible with [`github.com/swaggest/jsonschema-go interfaces`](https://github.com/swaggest/jsonschema-go#implementing-interfaces-on-a-type).
```

--------------------------------

### Request Parameter Locations

Source: https://github.com/swaggest/rest/blob/master/README.md

Lists the various locations from which input data can be populated into a request structure. These include path parameters, query parameters, form data, JSON bodies, cookies, and headers.

```APIDOC
Input data can be located in:
* `path` parameter in request URI, e.g. `/users/{name}`,
* `query` parameter in request URI, e.g. `/users?locale=en-US`,
* `formData` parameter in request body with `application/x-www-form-urlencoded` or `multipart/form-data` content,
* `form` parameter acts as `formData` or `query`,
* `json` parameter in request body with `application/json` content,
* `cookie` parameter in request cookie,
* `header` parameter in request header,
* `contentType` of matching raw request body.
```

--------------------------------

### Standalone Request Decoder Usage

Source: https://github.com/swaggest/rest/blob/master/README.md

Illustrates how to use the request decoder independently within an existing `ServeHTTP` method. It defines a request structure, creates a decoder, and then decodes an incoming `http.Request` into the structure.

```go
type MyRequest struct {
    Foo int    `header:"X-Foo"`
    Bar string `formData:"bar"`
    Baz bool   `query:"baz"`
}

// A decoder for particular structure, can be reused for multiple HTTP requests.
myDecoder := request.NewDecoderFactory().MakeDecoder(http.MethodPost, new(MyRequest), nil)

// Request and response writer from ServeHTTP.
var (
    rw  http.ResponseWriter
    req *http.Request
)

// This code would presumably live in ServeHTTP.
var myReq MyRequest

if err := myDecoder.Decode(req, &myReq, nil); err != nil {
    http.Error(rw, err.Error(), http.StatusBadRequest)
}
```

--------------------------------

### Embedded Swagger UI

Source: https://github.com/swaggest/rest/blob/master/README.md

Includes an embedded Swagger UI for interactive API documentation. This allows developers to easily explore and test API endpoints directly from the browser.

```go
import (
	"net/http"
	"github.com/swaggest/rest/web/swaggerui"
)

// Example of serving Swagger UI
func ServeSwaggerUI(mux *http.ServeMux) {
	// ... implementation details ...
}
```

--------------------------------

### HTTP Basic Auth Security

Source: https://github.com/swaggest/rest/blob/master/README.md

Configures HTTP Basic Authentication middleware for securing API endpoints. It involves preparing middleware for actual security checks and another for annotating handler documentation with the security schema. Both are applied to a specific route group.

```go
// Prepare middleware with suitable security schema.
// It will perform actual security check for every relevant request.
adminAuth := middleware.BasicAuth("Admin Access", map[string]string{"admin": "admin"})

// Prepare API schema updater middleware.
// It will annotate handler documentation with security schema.
adminSecuritySchema := nethttp.HTTPBasicSecurityMiddleware(apiSchema, "Admin", "Admin access")

// Endpoints with admin access.
r.Route("/admin", func(r chi.Router) {
    r.Group(func(r chi.Router) {
        r.Use(adminAuth, adminSecuritySchema) // Add both middlewares to routing group to enforce and document security.
        r.Method(http.MethodPut, "/hello/{name}", nethttp.NewHandler(u))
    })
})
```

--------------------------------

### Use Case Interactor Interface

Source: https://github.com/swaggest/rest/blob/master/README.md

Provides a generic interface for use case interactors, decoupling business logic from HTTP details. This adheres to Clean Architecture principles for maintainable code.

```go
import (
	"github.com/swaggest/usecase"
)

// Example of creating a use case interactor
func NewInteractor() usecase.Interactor {
	// ... implementation details ...
	return nil
}
```

--------------------------------

### Default Value Application and Custom Loading

Source: https://github.com/swaggest/rest/blob/master/README.md

Details how default tags are handled. By default, they only contribute to documentation. If `request.DecoderFactory.ApplyDefaults` is set to `true`, fields with default tags will be populated if they lack explicit values. Alternatively, implementing `request.Loader` allows for custom request data loading via the `LoadFromHTTPRequest` method.

```APIDOC
By default `default` tags are only contributing to documentation, 
if [`request.DecoderFactory.ApplyDefaults`](https://pkg.go.dev/github.com/swaggest/rest/request#DecoderFactory) is 
set to `true`, fields of request structure that don't have explicit value but have `default` will be populated with 
default value.

If input structure implements [`request.Loader`](https://pkg.go.dev/github.com/swaggest/rest/request#Loader),  
then `LoadFromHTTPRequest(r *http.Request) error` method will be invoked to populate input structure instead 
of automatic decoding. This allows low level control for cases that need it.
```

--------------------------------

### Request Control Interfaces

Source: https://github.com/swaggest/rest/blob/master/ADVANCED.md

Defines interfaces for controlling request handling within the framework. `LoadFromHTTPRequest` allows for full control over decoding and validation, bypassing automated processes. `SetRequest` provides access to the current `http.Request` without preventing automated decoding.

```APIDOC
Request Control:

LoadFromHTTPRequest(r *http.Request) error
  - Takes full control of request decoding and validating.
  - Prevents automated request decoding.
  - Parameters:
    - r: The http.Request object.
  - Returns: An error if decoding or validation fails.

SetRequest(r *http.Request)
  - Captures the current *http.Request.
  - Does not prevent automated request decoding.
  - Can be embedded into structures to gain access to the request.
  - Parameters:
    - r: The http.Request object.
```

--------------------------------

### Go Struct for Request Decoding (Simplified)

Source: https://github.com/swaggest/rest/blob/master/README.md

A simplified Go struct for request decoding, focusing on default values and validation patterns for 'Locale' and 'Name' fields. This version omits explicit parameter location tags.

```go
type helloInput struct {
    Locale string `default:"en-US" pattern:"^[a-z]{2}-[A-Z]{2}$"`
    Name   string `minLength:"3"` // Field tags define parameter location and JSON schema constraints.
}
```

--------------------------------

### Cookie-Based Session Security

Source: https://github.com/swaggest/rest/blob/master/README.md

Sets up security middleware using cookies for session management. It includes a middleware for processing session cookies and another for documenting the API key security in the cookie. This can be applied globally or to specific route groups.

```go
// Security middlewares.
//  - sessMW is the actual request-level processor,
//  - sessDoc is a handler-level wrapper to expose docs.
sessMW := func(handler http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        if c, err := r.Cookie("sessid"); err == nil {
            r = r.WithContext(context.WithValue(r.Context(), "sessionID", c.Value))
        }

        handler.ServeHTTP(w, r)
    })
}

sessDoc := nethttp.APIKeySecurityMiddleware(s.OpenAPICollector, "User",
    "sessid", oapi.InCookie, "Session cookie.")

// Security schema is configured for a single top-level route.
s.With(sessMW, sessDoc).Method(http.MethodGet, "/root-with-session", nethttp.NewHandler(dummy()))

// Security schema is configured on a sub-router.
s.Route("/deeper-with-session", func(r chi.Router) {
    r.Group(func(r chi.Router) {
        r.Use(sessMW, sessDoc)

        r.Method(http.MethodGet, "/one", nethttp.NewHandler(dummy()))
        r.Method(http.MethodGet, "/two", nethttp.NewHandler(dummy()))
    })
})
```

--------------------------------

### Response Encoder with Field Tags

Source: https://github.com/swaggest/rest/blob/master/README.md

Defines a Go struct with field tags to specify how data is encoded into HTTP responses. Tags like `header`, `json`, and `cookie` control placement and formatting.

```go
// Declare output port type.
type helloOutput struct {
    Now     time.Time `header:"X-Now" json:"-"`
    Message string    `json:"message"`
    Sess    string    `cookie:"sess,httponly,secure,max-age=86400,samesite=lax"`
}
```

--------------------------------

### HTTP Request Mapping

Source: https://github.com/swaggest/rest/blob/master/README.md

Maps HTTP requests into Go values based on field tags. This feature simplifies request handling by automatically parsing and validating incoming data.

```go
import (
	"net/http"
)

// Example of mapping HTTP request to a Go struct
func MapRequest(r *http.Request, target interface{}) error {
	// ... implementation details ...
	return nil
}
```

--------------------------------

### Request/Response JSON Schema Validation

Source: https://github.com/swaggest/rest/blob/master/README.md

Provides automatic request and response JSON schema validation using github.com/santhosh-tekuri/jsonschema. This enhances API reliability by ensuring data conforms to defined schemas.

```go
import (
	"github.com/santhosh-tekuri/jsonschema"
)

// Example of JSON schema validation
func ValidateRequest(data interface{}, schema interface{}) error {
	// ... implementation details ...
	return nil
}
```
Tokens:
Raw