README.md

Documentation: github.com/gin-contrib/cors

     1# CORS gin's middleware
     2
     3[![Run Tests](https://github.com/gin-contrib/cors/actions/workflows/go.yml/badge.svg)](https://github.com/gin-contrib/cors/actions/workflows/go.yml)
     4[![codecov](https://codecov.io/gh/gin-contrib/cors/branch/master/graph/badge.svg)](https://codecov.io/gh/gin-contrib/cors)
     5[![Go Report Card](https://goreportcard.com/badge/github.com/gin-contrib/cors)](https://goreportcard.com/report/github.com/gin-contrib/cors)
     6[![GoDoc](https://godoc.org/github.com/gin-contrib/cors?status.svg)](https://godoc.org/github.com/gin-contrib/cors)
     7
     8Gin middleware/handler to enable CORS support.
     9
    10## Usage
    11
    12### Start using it
    13
    14Download and install it:
    15
    16```sh
    17go get github.com/gin-contrib/cors
    18```
    19
    20Import it in your code:
    21
    22```go
    23import "github.com/gin-contrib/cors"
    24```
    25
    26### Canonical example
    27
    28```go
    29package main
    30
    31import (
    32  "time"
    33
    34  "github.com/gin-contrib/cors"
    35  "github.com/gin-gonic/gin"
    36)
    37
    38func main() {
    39  router := gin.Default()
    40  // CORS for https://foo.com and https://github.com origins, allowing:
    41  // - PUT and PATCH methods
    42  // - Origin header
    43  // - Credentials share
    44  // - Preflight requests cached for 12 hours
    45  router.Use(cors.New(cors.Config{
    46    AllowOrigins:     []string{"https://foo.com"},
    47    AllowMethods:     []string{"PUT", "PATCH"},
    48    AllowHeaders:     []string{"Origin"},
    49    ExposeHeaders:    []string{"Content-Length"},
    50    AllowCredentials: true,
    51    AllowOriginFunc: func(origin string) bool {
    52      return origin == "https://github.com"
    53    },
    54    MaxAge: 12 * time.Hour,
    55  }))
    56  router.Run()
    57}
    58```
    59
    60### Using DefaultConfig as start point
    61
    62```go
    63func main() {
    64  router := gin.Default()
    65  // - No origin allowed by default
    66  // - GET,POST, PUT, HEAD methods
    67  // - Credentials share disabled
    68  // - Preflight requests cached for 12 hours
    69  config := cors.DefaultConfig()
    70  config.AllowOrigins = []string{"http://google.com"}
    71  // config.AllowOrigins = []string{"http://google.com", "http://facebook.com"}
    72  // config.AllowAllOrigins = true
    73
    74  router.Use(cors.New(config))
    75  router.Run()
    76}
    77```
    78
    79Note: while Default() allows all origins, DefaultConfig() does not and you will still have to use AllowAllOrigins.
    80
    81### Default() allows all origins
    82
    83```go
    84func main() {
    85  router := gin.Default()
    86  // same as
    87  // config := cors.DefaultConfig()
    88  // config.AllowAllOrigins = true
    89  // router.Use(cors.New(config))
    90  router.Use(cors.Default())
    91  router.Run()
    92}
    93```
    94
    95Using all origins disables the ability for Gin to set cookies for clients. When dealing with credentials, don't allow all origins.
View as plain text