1
0
mirror of https://github.com/labstack/echo.git synced 2024-12-24 20:14:31 +02:00

docs: edit on github

Signed-off-by: Vishal Rana <vishal.rana@verizon.com>
This commit is contained in:
Vishal Rana 2016-11-16 22:46:00 -08:00
parent 4dc8cbd255
commit 57c7dccfbf
28 changed files with 143 additions and 190 deletions

View File

@ -8,14 +8,12 @@ description = "Context in Echo"
weight = 5
+++
## Context
`echo.Context` represents the context of the current HTTP request. It holds request and
response reference, path, path parameters, data, registered handler and APIs to read
request and write response. As Context is an interface, it is easy to extend it with
custom APIs.
#### Extending Context
## Extending Context
**Define a custom context**

View File

@ -7,8 +7,6 @@ description = "Handling cookie in Echo"
weight = 6
+++
## Cookies
Cookie is a small piece of data sent from a website and stored in the user's web
browser while the user is browsing. Every time the user loads the website, the browser
sends the cookie back to the server to notify the user's previous activity.
@ -19,7 +17,7 @@ in, or recording which pages were visited in the past). Cookies can also store
passwords and form content a user has previously entered, such as a credit card
number or an address.
### Cookie Attributes
## Cookie Attributes
Attribute | Optional
:--- | :---
@ -33,7 +31,7 @@ Attribute | Optional
Echo uses go standard `http.Cookie` object to add/retrieve cookies from the context received in the handler function.
### Create a Cookie
## Create a Cookie
```go
func writeCookie(c echo.Context) error {
@ -50,7 +48,7 @@ func writeCookie(c echo.Context) error {
- Attributes for the cookie are set assigning to the `http.Cookie` instance public attributes.
- Finally `c.SetCookie(cookies)` adds a `Set-Cookie` header in HTTP response.
### Read a Cookie
## Read a Cookie
```go
func readCookie(c echo.Context) error {
@ -67,7 +65,7 @@ func readCookie(c echo.Context) error {
- Cookie is read by name using `c.Cookie("username")` from the HTTP request.
- Cookie attributes are accessed using `Getter` function.
### Read all Cookies
## Read all Cookies
```go
func readAllCookies(c echo.Context) error {

View File

@ -7,9 +7,7 @@ description = "Customizing Echo"
weight = 3
+++
## Customization
### HTTP Error Handler
## HTTP Error Handler
Default HTTP error handler rules:
@ -20,20 +18,20 @@ and message `HTTPError.Message`.
You can also set a custom HTTP error handler using `Echo#HTTPErrorHandler`.
### Debugging
## Debugging
`Echo#Debug` enables/disables debug mode.
### Logging
## Logging
#### Log Output
### Log Output
`Echo#Logger.SetOutput(io.Writer)` sets the output destination for the logger.
Default value `os.Stdout`
To completely disable logs use `Echo#Logger.SetOutput(io.Discard)` or `Echo#Logger.SetLevel(log.OFF)`
#### Log Level
### Log Level
`Echo#Logger.SetLevel(log.Lvl)`

View File

@ -7,8 +7,6 @@ description = "Error handling in Echo"
weight = 8
+++
## Error Handling
Echo advocates centralized HTTP error handling by returning error from middleware
or handlers.

View File

@ -7,8 +7,6 @@ description = "Frequently asked questions in Echo"
weight = 20
+++
## FAQ
Q: How to retrieve `*http.Request` and `http.ResponseWriter` from `echo.Context`?
- `http.Request` > `c.Request()`

View File

@ -7,8 +7,6 @@ description = "Installing Echo"
weight = 1
+++
## Installation
Echo is developed and tested using Go `1.6.x` and `1.7.x`
```sh

View File

@ -7,9 +7,7 @@ description = "Migration"
weight = 2
+++
## V3
### Change Log
## Change Log
- Automatic TLS certificates via [Let's Encrypt](https://letsencrypt.org/)
- Built-in support for graceful shutdown
@ -47,4 +45,4 @@ description = "Migration"
- Moved website and recipes to the main repo
- Updated docs and fixed numerous issues
### [Recipes](/recipes/hello-world)
## [Recipes](/recipes/hello-world)

View File

@ -1,5 +1,5 @@
+++
title = "HTTP Request"
title = "Request"
description = "Handling HTTP request in Echo"
[menu.side]
name = "Request"
@ -7,9 +7,7 @@ description = "Handling HTTP request in Echo"
weight = 6
+++
## Request
### Bind Request Body
## Bind Request Body
To bind request body into a provided Go type use `Context#Bind(interface{})`.
The default binder supports decoding application/json, application/xml and
@ -21,7 +19,7 @@ TODO
> Custom binder can be registered via `Echo#SetBinder(Binder)`
### Query Parameter
## Query Parameter
Query parameter can be retrieved by name using `Context#QueryParam(name string)`.
@ -38,7 +36,7 @@ e.GET("/users", func(c echo.Context) error {
$ curl -G -d "name=joe" http://localhost:1323/users
```
### Form Parameter
## Form Parameter
Form parameter can be retrieved by name using `Context#FormValue(name string)`.
@ -55,7 +53,7 @@ e.POST("/users", func(c echo.Context) error {
$ curl -d "name=joe" http://localhost:1323/users
```
### Path Parameter
## Path Parameter
Registered path parameter can be retrieved by name `Context#Param(name string) string`.
@ -75,7 +73,7 @@ $ curl http://localhost:1323/users/joe
```
### Handler Path
## Handler Path
`Context#Path()` returns the registered path for the handler, it can be used in the
middleware for logging purpose.

View File

@ -1,5 +1,5 @@
+++
title = "HTTP Routing"
title = "Routing"
description = "Routing HTTP request in Echo"
[menu.side]
name = "Routing"
@ -7,8 +7,6 @@ description = "Routing HTTP request in Echo"
weight = 4
+++
## Routing
Echo's router is [fast, optimized]({{< ref "index.md#performance">}}) and
flexible. It's based on [radix tree](http://en.wikipedia.org/wiki/Radix_tree) data
structure which makes route lookup really fast. Router leverages [sync pool](https://golang.org/pkg/sync/#Pool)
@ -34,7 +32,7 @@ If you want to register it for some methods use `Echo.Match(methods []string, pa
Echo defines handler function as `func(echo.Context) error` where `echo.Context` primarily
holds HTTP request and response interfaces.
### Match-any
## Match-any
Matches zero or more characters in the path. For example, pattern `/users/*` will
match:
@ -44,13 +42,13 @@ match:
- `/users/1/files/1`
- `/users/anything...`
### Path matching order
## Path matching order
- Static
- Param
- Match any
#### Example
### Example
```go
e.GET("/users/:id", func(c echo.Context) error {
@ -74,7 +72,7 @@ Above routes would resolve in the following order:
> Routes can be written in any order.
### Group
## Group
`Echo#Group(prefix string, m ...Middleware) *Group`
@ -96,7 +94,7 @@ g.Use(middleware.BasicAuth(func(username, password string) bool {
}))
```
### URI building
## URI building
`Echo.URI` can be used to generate URI for any handler with specified path parameters.
It's helpful to centralize all your URI patterns which ease in refactoring your

View File

@ -9,9 +9,7 @@ description = "Serving static files in Echo"
Images, JavaScript, CSS, PDF, Fonts and so on...
## Static Files
### Using `Echo#Static()`
## Using `Echo#Static()`
`Echo#Static(prefix, root string)` registers a new route with path prefix to serve
static files from the provided root directory.
@ -36,7 +34,7 @@ e.Static("/", "assets")
Example above will serve any file from the assets directory for path `/*`. For example,
a request to `/js/main.js` will fetch and serve `assets/js/main.js` file.
### Using `Echo#File()`
## Using `Echo#File()`
`Echo#File(path, file string)` registers a new route with path to serve a static
file.

View File

@ -7,9 +7,7 @@ description = "How to use templates in Echo"
weight = 3
+++
## Templates
### Template Rendering
## Template Rendering
`Context#Render(code int, name string, data interface{}) error` renders a template
with data and sends a text/html response with status code. Templates can be registered

View File

@ -7,16 +7,14 @@ description = "Testing handler and middleware in Echo"
weight = 9
+++
## Testing
### Testing Handler
## Testing Handler
`GET` `/users/:id`
Handler below retrieves user by id from the database. If user is not found it returns
`404` error with a message.
#### CreateUser
### CreateUser
`POST` `/users`
@ -24,7 +22,7 @@ Handler below retrieves user by id from the database. If user is not found it re
- On success `201 - Created`
- On error `500 - Internal Server Error`
#### GetUser
### GetUser
`GET` `/users/:email`
@ -130,7 +128,7 @@ func TestGetUser(t *testing.T) {
}
```
#### Using Form Payload
### Using Form Payload
```go
f := make(url.Values)
@ -139,14 +137,14 @@ f.Set("email", "jon@labstack.com")
req, err := http.NewRequest(echo.POST, "/", strings.NewReader(f.Encode()))
```
#### Setting Path Params
### Setting Path Params
```go
c.SetParamNames("id", "email")
c.SetParamValues("1", "jon@labstack.com")
```
#### Setting Query Params
### Setting Query Params
```go
q := make(url.Values)
@ -154,7 +152,7 @@ q.Set("email", "jon@labstack.com")
req, err := http.NewRequest(echo.POST, "/?"+q.Encode(), nil)
```
### Testing Middleware
## Testing Middleware
*TBD*

View File

@ -1,6 +1,6 @@
+++
title = "CORS Recipe"
description = "CORS recipe / example for Echo"
title = "CORS Example"
description = "CORS example for Echo"
[menu.side]
name = "CORS"
identifier = "cors-middleware"
@ -8,16 +8,14 @@ description = "CORS recipe / example for Echo"
weight = 3
+++
## CORS Recipe
### Server
## Server
`server.go`
{{< embed "cors/server.go" >}}
### Maintainers
## Maintainers
- [vishr](https://github.com/vishr)
### [Source Code]({{< source "cors" >}})
## [Source Code]({{< source "cors" >}})

View File

@ -1,25 +1,23 @@
+++
title = "CRUD Recipe"
description = "CRUD (Create, read, update and delete) recipe / example for Echo"
title = "CRUD Example"
description = "CRUD (Create, read, update and delete) example for Echo"
[menu.side]
name = "CRUD"
parent = "recipes"
weight = 2
+++
## CRUD (Create, read, update and delete) Recipe
### Server
## Server
`server.go`
{{< embed "crud/server.go" >}}
### Client
## Client
`curl`
#### Create User
### Create User
```sh
curl -X POST \
@ -37,7 +35,7 @@ curl -X POST \
}
```
#### Get User
### Get User
```sh
curl localhost:1323/users/1
@ -52,7 +50,7 @@ curl localhost:1323/users/1
}
```
#### Update User
### Update User
```sh
curl -X PUT \
@ -70,7 +68,7 @@ curl -X PUT \
}
```
#### Delete User
### Delete User
```sh
curl -X DELETE localhost:1323/users/1
@ -80,8 +78,8 @@ curl -X DELETE localhost:1323/users/1
`NoContent - 204`
### Maintainers
## Maintainers
- [vishr](https://github.com/vishr)
### [Source Code]({{< source "crud" >}})
## [Source Code]({{< source "crud" >}})

View File

@ -1,23 +1,21 @@
+++
title = "Embed Resources Recipe"
description = "Embed resources recipe / example for Echo"
title = "Embed Resources Example"
description = "Embed resources example for Echo"
[menu.side]
name = "Embed Resources"
parent = "recipes"
weight = 14
+++
## Embed Resources Recipe
### With go.rice
## With go.rice
`server.go`
{{< embed "embed-resources/server.go" >}}
### Maintainers
## Maintainers
- [caarlos0](https://github.com/caarlos0)
- [maddie](https://github.com/maddie)
### [Source Code]({{< source "embed-resources" >}})
## [Source Code]({{< source "embed-resources" >}})

View File

@ -1,47 +1,45 @@
+++
title = "File Upload Recipe"
description = "File upload recipe / example for Echo"
title = "File Upload Example"
description = "File upload example for Echo"
[menu.side]
name = "File Upload"
parent = "recipes"
weight = 7
+++
## File Upload Recipe
## How to upload single file with fields?
### How to upload single file with fields?
#### Server
### Server
`server.go`
{{< embed "file-upload/single/server.go" >}}
#### Client
### Client
`index.html`
{{< embed "file-upload/single/public/index.html" >}}
### How to upload multiple files with fields?
## How to upload multiple files with fields?
#### Server
### Server
`server.go`
{{< embed "file-upload/multiple/server.go" >}}
#### Client
### Client
`index.html`
{{< embed "file-upload/multiple/public/index.html" >}}
### Maintainers
## Maintainers
- [vishr](https://github.com/vishr)
### Source Code
## Source Code
- [single]({{< source "file-upload/single" >}})
- [multiple]({{< source "file-upload/multiple" >}})

View File

@ -1,14 +1,12 @@
+++
title = "Google App Engine Recipe"
description = "Google App Engine recipe / example for Echo"
title = "Google App Engine Example"
description = "Google App Engine example for Echo"
[menu.side]
name = "Google App Engine"
parent = "recipes"
weight = 12
+++
## Google App Engine Recipe
Google App Engine (GAE) provides a range of hosting options from pure PaaS (App Engine Classic)
through Managed VMs to fully self-managed or container-driven Compute Engine instances. Echo
works great with all of these but requires a few changes to the usual examples to run on the
@ -17,7 +15,7 @@ to produce a codebase that will run on these and also non-managed platforms auto
We'll walk through the changes needed to support each option.
### Standalone
## Standalone
Wait? What? I thought this was about AppEngine! Bear with me - the easiest way to show the changes
required is to start with a setup for standalone and work from there plus there's no reason we
@ -59,7 +57,7 @@ Echo instance directly (so things like CORS middleware can be added at this high
If we run our app it should execute as it did before when everything was in one file although we have
at least gained the ability to organize our handlers a little more cleanly.
### AppEngine Classic and Managed VMs
## AppEngine Classic and Managed VMs
So far we've seen how to split apart the Echo creation and setup but still have the same app that
still only runs standalone. Now we'll see hwo those changes allow us to add support for AppEngine
@ -68,7 +66,7 @@ hosting.
Refer to the [AppEngine site](https://cloud.google.com/appengine/docs/go/) for full configuration
and deployment information.
#### app.yaml configuration file
### app.yaml configuration file
Both of these are Platform as as Service options running on either sandboxed micro-containers
or managed Compute Engine instances. Both require an `app.yaml` file to describe the app to
@ -85,7 +83,7 @@ this can help when making the transition from AppEngine Classic to Managed VMs.
{{< embed "google-app-engine/app-engine.yaml" >}}
#### Router configuration
### Router configuration
We'll now use the [build constraints](http://golang.org/pkg/go/build/) again like we did when creating
our `app-standalone.go` instance but this time with the opposite tags to use this file _if_ the build has
@ -131,8 +129,8 @@ switching between AppEngine provided service such as Datastore and alternative s
such as MongoDB. A combination of go interfaces and build constraints can make this fairly straightforward
but is outside the scope of this recipe.
### Maintainers
## Maintainers
- [CaptainCodeman](https://github.com/CaptainCodeman)
### [Source Code]({{< source "google-app-engine" >}})
## [Source Code]({{< source "google-app-engine" >}})

View File

@ -1,29 +1,27 @@
+++
title = "Graceful Shutdown Recipe"
description = "Graceful shutdown recipe / example for Echo"
title = "Graceful Shutdown Example"
description = "Graceful shutdown example for Echo"
[menu.side]
name = "Graceful Shutdown"
parent = "recipes"
weight = 13
+++
## Graceful Shutdown Recipe
Echo now ships with graceful server termination inside it, to accomplish it Echo uses `github.com/tylerb/graceful` library.
By Default echo uses 15 seconds as shutdown timeout, giving 15 secs to open connections at the time the server starts to shut-down.
In order to change this default 15 seconds you could change the `ShutdownTimeout` property of your Echo instance as needed by doing something like:
Echo now ships with graceful server termination inside it, to accomplish it Echo
uses `github.com/tylerb/graceful` library. By Default echo uses 15 seconds as shutdown
timeout, giving 15 secs to open connections at the time the server starts to shut-down.
In order to change this default 15 seconds you could change the `ShutdownTimeout`
property of your Echo instance as needed by doing something like:
`server.go`
{{< embed "graceful-shutdown/server.go" >}}
### Maintainers
## Maintainers
- [mertenvg](https://github.com/mertenvg)
- [apaganobeleno](https://github.com/apaganobeleno)
### Source Code
## Source Code
- [graceful]({{< source "graceful-shutdown/graceful" >}})

View File

@ -1,22 +1,20 @@
+++
title = "Hello World Recipe"
description = "Hello world recipe / example for Echo"
title = "Hello World Example"
description = "Hello world example for Echo"
[menu.side]
name = "Hello World"
parent = "recipes"
weight = 1
+++
## Hello World Recipe
### Server
## Server
`server.go`
{{< embed "hello-world/server.go" >}}
### Maintainers
## Maintainers
- [vishr](https://github.com/vishr)
### [Source Code]({{< source "hello-world" >}})
## [Source Code]({{< source "hello-world" >}})

View File

@ -1,6 +1,6 @@
+++
title = "HTTP/2 Recipe"
description = "HTTP/2 recipe / example for Echo"
title = "HTTP/2 Example"
description = "HTTP/2 example for Echo"
[menu.side]
name = "HTTP/2"
parent = "recipes"
@ -21,8 +21,6 @@ protocol used by the World Wide Web
## How to run an HTTP/2 and HTTPS server?
> Standard engine only
### Generate a self-signed X.509 TLS certificate (HTTP/2 requires TLS to operate)
```sh
@ -45,8 +43,8 @@ a certificate from [CA](https://en.wikipedia.org/wiki/Certificate_authority).
- https://localhost:1323/request (Displays the information about received HTTP request)
- https://localhost:1323/stream (Streams the current time every second)
### Maintainers
## Maintainers
- [vishr](https://github.com/vishr)
### [Source Code]({{< source "http2" >}})
## [Source Code]({{< source "http2" >}})

View File

@ -1,30 +1,28 @@
+++
title = "JSONP Recipe"
description = "JSONP recipe / example for Echo"
title = "JSONP Example"
description = "JSONP example for Echo"
[menu.side]
name = "JSONP"
parent = "recipes"
weight = 6
+++
## JSONP Recipe
JSONP is a method that allows cross-domain server calls. You can read more about it at the JSON versus JSONP Tutorial.
### Server
## Server
`server.go`
{{< embed "jsonp/server.go" >}}
### Client
## Client
`index.html`
{{< embed "jsonp/public/index.html" >}}
### Maintainers
## Maintainers
- [willf](https://github.com/willf)
### [Source Code]({{< source "jsonp" >}})
## [Source Code]({{< source "jsonp" >}})

View File

@ -1,6 +1,6 @@
+++
title = "JWT Recipe"
description = "JWT recipe / example for Echo"
title = "JWT Example"
description = "JWT example for Echo"
[menu.side]
name = "JWT"
identifier = "jwt-recipe"
@ -8,28 +8,26 @@ description = "JWT recipe / example for Echo"
weight = 11
+++
## JWT Recipe
- JWT authentication using HS256 algorithm.
- JWT is retrieved from `Authorization` request header.
### Server using Map claims
## Server using Map claims
`server.go`
{{< embed "jwt/map-claims/server.go" >}}
### Server using custom claims
## Server using custom claims
`server.go`
{{< embed "jwt/custom-claims/server.go" >}}
### Client
## Client
`curl`
#### Login
### Login
Login using username and password to retrieve a token.
@ -45,7 +43,7 @@ curl -X POST -d 'username=jon' -d 'password=shhh!' localhost:1323/login
}
```
#### Request
### Request
Request a restricted resource using the token in `Authorization` request header.
@ -59,13 +57,13 @@ curl localhost:1323/restricted -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR
Welcome Jon Snow!
```
### Maintainers
## Maintainers
- [vishr](https://github.com/vishr)
- [axdg](https://github.com/axdg)
- [matcornic](https://github.com/matcornic)
### Source Code
## Source Code
- [With default Map claims]({{< source "jwt/map-claims" >}})
- [With custom claims]({{< source "jwt/custom-claims" >}})

View File

@ -1,26 +1,24 @@
+++
title = "Middleware Recipe"
description = "Middleware recipe / example for Echo"
title = "Middleware Example"
description = "Middleware example for Echo"
[menu.side]
name = "Middleware"
parent = "recipes"
weight = 3
+++
## Middleware Recipe
### How to write a custom middleware?
## How to write a custom middleware?
- Middleware to collect request count, statuses and uptime.
- Middleware to write custom `Server` header to the response.
#### Server
### Server
`server.go`
{{< embed "middleware/server.go" >}}
#### Response
### Response
*Headers*
```sh
@ -43,8 +41,8 @@ Server:Echo/2.0
}
```
### Maintainers
## Maintainers
- [vishr](https://github.com/vishr)
### [Source Code]({{< source "middleware" >}})
## [Source Code]({{< source "middleware" >}})

View File

@ -1,30 +1,28 @@
+++
title = "Streaming Response Recipe"
description = "Streaming response recipe / example for Echo"
title = "Streaming Response Example"
description = "Streaming response example for Echo"
[menu.side]
name = "Streaming Response"
parent = "recipes"
weight = 3
+++
## Streaming Response Recipe
- Send data as it is produced
- Streaming JSON response with chunked transfer encoding
### Server
## Server
`server.go`
{{< embed "streaming-response/server.go" >}}
### Client
## Client
```sh
$ curl localhost:1323
```
### Output
## Output
```sh
{"Altitude":-97,"Latitude":37.819929,"Longitude":-122.478255}
@ -34,8 +32,8 @@ $ curl localhost:1323
{"Altitude":15,"Latitude":37.77493,"Longitude":-122.419416}
```
### Maintainers
## Maintainers
- [vishr](https://github.com/vishr)
### [Source Code]({{< source "streaming-response" >}})
## [Source Code]({{< source "streaming-response" >}})

View File

@ -1,21 +1,19 @@
+++
title = "Subdomains Recipe"
description = "Subdomains recipe / example for Echo"
title = "Subdomains Example"
description = "Subdomains example for Echo"
[menu.side]
name = "Subdomains"
parent = "recipes"
weight = 10
+++
## Subdomains Recipe
`server.go`
{{< embed "subdomains/server.go" >}}
### Maintainers
## Maintainers
- [axdg](https://github.com/axdg)
- [vishr](https://github.com/vishr)
### [Source Code]({{< source "subdomains" >}})
## [Source Code]({{< source "subdomains" >}})

View File

@ -1,39 +1,35 @@
+++
title = "WebSocket Recipe"
description = "WebSocket recipe / example for Echo"
title = "WebSocket Example"
description = "WebSocket example for Echo"
[menu.side]
name = "WebSocket"
parent = "recipes"
weight = 5
+++
## WebSocket Recipe
## Using `net` WebSocket
> Only supported in `standard` engine.
### Using `net` WebSocket
#### Server
### Server
`server.go`
{{< embed "websocket/net/server.go" >}}
### Using `gorilla` WebSocket
## Using `gorilla` WebSocket
#### Server
### Server
`server.go`
{{< embed "websocket/gorilla/server.go" >}}
### Client
## Client
`index.html`
{{< embed "websocket/public/index.html" >}}
### Output
## Output
`Client`
@ -55,8 +51,8 @@ Hello, Server!
Hello, Server!
```
### Maintainers
## Maintainers
- [vishr](https://github.com/vishr)
### [Source Code]({{< source "websocket" >}})
## [Source Code]({{< source "websocket" >}})

View File

@ -2,8 +2,6 @@
title = "Support Echo"
+++
## Support Echo Development
<p>
<a href="https://patreon.com/labstack" target="_blank"><br>
<img style="width: 120px;" src="https://s3.amazonaws.com/patreon_public_assets/toolbox/patreon.png"><br>

View File

@ -10,9 +10,18 @@
{{ partial "notice.html" }}
<article class="content">
<section>
<h1>{{ .Title }}</h1>
{{ .Content }}
</section>
<footer style="margin-top: 40px;">
<footer>
<div class="w3-panel w3-pale-yellow w3-leftbar w3-border-yellow">
<p>
<i class="fa fa-pencil" aria-hidden="true"></i>
<a href="https://github.com/labstack/echo/blob/master/website/content/{{ .File.Path }}">
Edit this page on GitHub
</a>
</p>
</div>
</footer>
</article>
</div>