Add examples

examples/README.md

@@ -0,0 +1,4 @@
+This example shows how Echoswagger create a Swagger UI document page automatically.
+
+The doc contents in this example is very similar to the default example in http://editor.swagger.io/
+

examples/controller_pet.go

@@ -0,0 +1,153 @@
+package main
+
+import (
+	"net/http"
+
+	"github.com/elvinchan/echoswagger"
+	"github.com/labstack/echo"
+)
+
+type PetController struct{}
+
+func (c PetController) Init(g echoswagger.ApiGroup) {
+	g.SetDescription("Everything about your Pets").
+		SetExternalDocs("Find out more", "http://swagger.io")
+
+	security := map[string][]string{
+		"petstore_auth": []string{"write:pets", "read:pets"},
+	}
+
+	type Category struct {
+		Id   int64  `json:"id"`
+		Name string `json:"name"`
+	}
+	type Tag struct {
+		Id   int64  `json:"id"`
+		Name string `json:"name"`
+	}
+	type Pet struct {
+		Id        int64    `json:"id"`
+		Category  Category `json:"category"`
+		Name      string   `json:"name" swagger:"required"`
+		PhotoUrls []string `json:"photoUrls" xml:"photoUrl" swagger:"required"`
+		Tags      []Tag    `json:"tags" xml:"tag"`
+		Status    string   `json:"status" swagger:"enum(available|pending|sold),desc(pet status in the store)"`
+	}
+	pet := Pet{Name: "doggie"}
+	g.POST("", c.Create).
+		AddParamBody(&pet, "body", "Pet object that needs to be added to the store", true).
+		AddResponse(http.StatusMethodNotAllowed, "Invalid input", nil, nil).
+		SetRequestContentType("application/json", "application/xml").
+		SetOperationId("addPet").
+		SetSummary("Add a new pet to the store").
+		SetSecurityWithScope(security)
+
+	g.PUT("", c.Update).
+		AddParamBody(&pet, "body", "Pet object that needs to be added to the store", true).
+		AddResponse(http.StatusBadRequest, "Invalid ID supplied", nil, nil).
+		AddResponse(http.StatusNotFound, "Pet not found", nil, nil).
+		AddResponse(http.StatusMethodNotAllowed, "Validation exception", nil, nil).
+		SetRequestContentType("application/json", "application/xml").
+		SetOperationId("updatePet").
+		SetSummary("Update an existing pet").
+		SetSecurityWithScope(security)
+
+	type StatusParam struct {
+		Status []string `query:"status" swagger:"required,desc(Status values that need to be considered for filter),default(available),enum(available|pending|sold)"`
+	}
+	g.GET("/findByStatus", c.FindByStatus).
+		AddParamQueryNested(&StatusParam{}).
+		AddResponse(http.StatusOK, "successful operation", &[]Pet{pet}, nil).
+		AddResponse(http.StatusBadRequest, "Invalid status value", nil, nil).
+		SetOperationId("findPetsByStatus").
+		SetDescription("Multiple status values can be provided with comma separated strings").
+		SetSummary("Finds Pets by status").
+		SetSecurityWithScope(security)
+
+	g.GET("/findByTags", c.FindByTags).
+		AddParamQuery([]string{}, "tags", "Tags to filter by", true).
+		AddResponse(http.StatusOK, "successful operation", &[]Pet{pet}, nil).
+		AddResponse(http.StatusBadRequest, "Invalid tag value", nil, nil).
+		SetOperationId("findPetsByTags").
+		SetDeprecated().
+		SetDescription("Muliple tags can be provided with comma separated strings. Use         tag1, tag2, tag3 for testing.").
+		SetSummary("Finds Pets by tags").
+		SetSecurityWithScope(security)
+
+	g.GET("/{petId}", c.GetById).
+		AddParamPath(0, "petId", "ID of pet to return").
+		AddResponse(http.StatusOK, "successful operation", &pet, nil).
+		AddResponse(http.StatusBadRequest, "Invalid ID supplied", nil, nil).
+		AddResponse(http.StatusNotFound, "Pet not found", nil, nil).
+		SetOperationId("getPetById").
+		SetDescription("Returns a single pet").
+		SetSummary("Find pet by ID").
+		SetSecurity("api_key")
+
+	g.POST("/{petId}", c.CreateById).
+		AddParamPath(0, "petId", "ID of pet that needs to be updated").
+		AddParamForm("", "name", "Updated name of the pet", false).
+		AddParamForm("", "status", "Updated status of the pet", false).
+		AddResponse(http.StatusMethodNotAllowed, "Invalid input", nil, nil).
+		SetRequestContentType("application/x-www-form-urlencoded").
+		SetOperationId("updatePetWithForm").
+		SetSummary("Updates a pet in the store with form data").
+		SetSecurityWithScope(security)
+
+	g.DELETE("/{petId}", c.DeleteById).
+		AddParamHeader("", "api_key", "", false).
+		AddParamPath(int64(0), "petId", "Pet id to delete").
+		AddResponse(http.StatusBadRequest, "Invalid ID supplied", nil, nil).
+		AddResponse(http.StatusNotFound, "Pet not found", nil, nil).
+		SetOperationId("deletePet").
+		SetSummary("Deletes a pet").
+		SetSecurityWithScope(security)
+
+	type ApiResponse struct {
+		Code    int32  `json:"code"`
+		Type    string `json:"type"`
+		Message string `json:"message"`
+	}
+	g.POST("/{petId}/uploadImage", c.UploadImageById).
+		AddParamPath("", "petId", "ID of pet to update").
+		AddParamForm("", "additionalMetadata", "Additional data to pass to server", false).
+		AddParamFile("file", "file to upload", false).
+		AddResponse(http.StatusOK, "successful operation", &ApiResponse{}, nil).
+		SetRequestContentType("multipart/form-data").
+		SetResponseContentType("application/json").
+		SetOperationId("uploadFile").
+		SetSummary("uploads an image").
+		SetSecurityWithScope(security)
+}
+
+func (PetController) Create(c echo.Context) error {
+	return nil
+}
+
+func (PetController) Update(c echo.Context) error {
+	return nil
+}
+
+func (PetController) FindByStatus(c echo.Context) error {
+	return nil
+}
+
+func (PetController) FindByTags(c echo.Context) error {
+	return nil
+}
+
+func (PetController) GetById(c echo.Context) error {
+	return nil
+}
+
+func (PetController) CreateById(c echo.Context) error {
+	return nil
+}
+
+func (PetController) DeleteById(c echo.Context) error {
+	return nil
+}
+
+func (PetController) UploadImageById(c echo.Context) error {
+	return nil
+}

examples/controller_store.go

@@ -0,0 +1,77 @@
+package main
+
+import (
+	"net/http"
+	"time"
+
+	"github.com/elvinchan/echoswagger"
+	"github.com/labstack/echo"
+)
+
+type StoreController struct{}
+
+func (c StoreController) Init(g echoswagger.ApiGroup) {
+	g.SetDescription("Access to Petstore orders")
+
+	g.GET("/inventory", c.GetInventory).
+		AddResponse(http.StatusOK, "successful operation", map[string]int32{}, nil).
+		SetResponseContentType("application/json").
+		SetOperationId("getInventory").
+		SetDescription("Returns a map of status codes to quantities").
+		SetSummary("Returns pet inventories by status").
+		SetSecurity("api_key")
+
+	type Order struct {
+		Id       int64     `json:"id"`
+		PetId    int64     `json:"petId"`
+		Quantity int64     `json:"quantity"`
+		ShipDate time.Time `json:"shipDate"`
+		Status   string    `json:"status" swagger:"desc(Order Status),enum(placed|approved|delivered)"`
+		Complete bool      `json:"complete" swagger:"default(false)"`
+	}
+	g.POST("/order", c.CreateOrder).
+		AddParamBody(Order{}, "body", "order placed for purchasing the pet", true).
+		AddResponse(http.StatusOK, "successful operation", Order{}, nil).
+		AddResponse(http.StatusBadRequest, "Invalid Order", nil, nil).
+		SetOperationId("placeOrder").
+		SetSummary("Place an order for a pet")
+
+	type GetOrderId struct {
+		orderId int64 `swagger:"max(10.0),min(1.0),desc(ID of pet that needs to be fetched)"`
+	}
+	g.GET("/order/{orderId}", c.GetOrderById).
+		AddParamPathNested(&GetOrderId{}).
+		AddResponse(http.StatusOK, "successful operation", Order{}, nil).
+		AddResponse(http.StatusBadRequest, "Invalid ID supplied", nil, nil).
+		AddResponse(http.StatusNotFound, "Order not found", nil, nil).
+		SetOperationId("getOrderById").
+		SetDescription("For valid response try integer IDs with value >= 1 and <= 10.         Other values will generated exceptions").
+		SetSummary("Find purchase order by ID")
+
+	type DeleteOrderId struct {
+		orderId int64 `swagger:"min(1.0),desc(ID of the order that needs to be deleted)"`
+	}
+	g.DELETE("/order/{orderId}", c.DeleteOrderById).
+		AddParamPathNested(&DeleteOrderId{}).
+		AddResponse(http.StatusBadRequest, "Invalid ID supplied", nil, nil).
+		AddResponse(http.StatusNotFound, "Order not found", nil, nil).
+		SetOperationId("deleteOrder").
+		SetDescription("For valid response try integer IDs with positive integer value.         Negative or non-integer values will generate API errors").
+		SetSummary("Delete purchase order by ID")
+}
+
+func (StoreController) GetInventory(c echo.Context) error {
+	return nil
+}
+
+func (StoreController) CreateOrder(c echo.Context) error {
+	return nil
+}
+
+func (StoreController) GetOrderById(c echo.Context) error {
+	return nil
+}
+
+func (StoreController) DeleteOrderById(c echo.Context) error {
+	return nil
+}

examples/controller_user.go

@@ -0,0 +1,118 @@
+package main
+
+import (
+	"encoding/xml"
+	"net/http"
+	"time"
+
+	"github.com/elvinchan/echoswagger"
+	"github.com/labstack/echo"
+)
+
+type UserController struct{}
+
+func (c UserController) Init(g echoswagger.ApiGroup) {
+	g.SetDescription("Operations about user").
+		SetExternalDocs("Find out more about our store", "http://swagger.io")
+
+	type User struct {
+		X          xml.Name `xml:"Users"`
+		Id         int64    `json:"id"`
+		UserName   string   `json:"username"`
+		FirstName  string   `json:"firstname"`
+		LastName   string   `json:"lastname"`
+		Email      string   `json:"email"`
+		Password   string   `json:"password"`
+		Phone      string   `json:"phone"`
+		UserStatus int32    `json:"userStatus" swagger:"desc(User Status)"`
+	}
+	g.POST("", c.Create).
+		AddParamBody(&User{}, "body", "Created user object", true).
+		SetOperationId("createUser").
+		SetDescription("This can only be done by the logged in user.").
+		SetSummary("Create user")
+
+	g.POST("/createWithArray", c.CreateWithArray).
+		AddParamBody(&[]User{}, "body", "List of user object", true).
+		SetOperationId("createUsersWithArrayInput").
+		SetRequestContentType("application/json", "application/xml").
+		SetSummary("Creates list of users with given input array")
+
+	g.POST("/createWithList", c.CreateWithList).
+		AddParamBody(&[]User{}, "body", "List of user object", true).
+		SetOperationId("createUsersWithListInput").
+		SetSummary("Creates list of users with given input array")
+
+	type ResponseHeader struct {
+		XRateLimit    int32     `json:"X-Rate-Limit" swagger:"desc(calls per hour allowed by the user)"`
+		XExpiresAfter time.Time `json:"X-Expires-After" swagger:"desc(date in UTC when token expires)"`
+	}
+	g.GET("/login", c.Login).
+		AddParamQuery("", "username", "The user name for login", true).
+		AddParamQuery("", "password", "The password for login in clear text", true).
+		AddResponse(http.StatusOK, "successful operation", "", ResponseHeader{}).
+		AddResponse(http.StatusBadRequest, "Invalid username/password supplied", nil, nil).
+		SetOperationId("loginUser").
+		SetSummary("Logs user into the system")
+
+	g.GET("/logout", c.Logout).
+		SetOperationId("logoutUser").
+		SetSummary("Logs out current logged in user session")
+
+	g.GET("/{username}", c.GetByUsername).
+		AddParamPath("", "username", "The name that needs to be fetched. Use user1 for testing. ").
+		AddResponse(http.StatusOK, "successful operation", &User{}, nil).
+		AddResponse(http.StatusBadRequest, "Invalid username supplied", nil, nil).
+		AddResponse(http.StatusNotFound, "User not found", nil, nil).
+		SetOperationId("getUserByName").
+		SetSummary("Get user by user name")
+
+	g.PUT("/{username}", c.UpdateByUsername).
+		AddParamPath("", "username", "name that need to be updated").
+		AddParamBody(&User{}, "body", "Updated user object", true).
+		AddResponse(http.StatusBadRequest, "Invalid user supplied", nil, nil).
+		AddResponse(http.StatusNotFound, "User not found", nil, nil).
+		SetOperationId("updateUser").
+		SetDescription("This can only be done by the logged in user.").
+		SetSummary("Updated user")
+
+	g.DELETE("/{username}", c.DeleteByUsername).
+		AddParamPath("", "username", "The name that needs to be deleted").
+		AddResponse(http.StatusBadRequest, "Invalid username supplied", nil, nil).
+		AddResponse(http.StatusNotFound, "User not found", nil, nil).
+		SetOperationId("deleteUser").
+		SetDescription("This can only be done by the logged in user.").
+		SetSummary("Delete user")
+}
+
+func (UserController) Create(c echo.Context) error {
+	return nil
+}
+
+func (UserController) CreateWithArray(c echo.Context) error {
+	return nil
+}
+
+func (UserController) CreateWithList(c echo.Context) error {
+	return nil
+}
+
+func (UserController) Login(c echo.Context) error {
+	return nil
+}
+
+func (UserController) Logout(c echo.Context) error {
+	return nil
+}
+
+func (UserController) GetByUsername(c echo.Context) error {
+	return nil
+}
+
+func (UserController) UpdateByUsername(c echo.Context) error {
+	return nil
+}
+
+func (UserController) DeleteByUsername(c echo.Context) error {
+	return nil
+}

examples/main.go

@@ -0,0 +1,46 @@
+package main
+
+import (
+	"github.com/elvinchan/echoswagger"
+	"github.com/labstack/echo"
+)
+
+func main() {
+	e := initServer().Echo()
+	e.Logger.Fatal(e.Start(":1323"))
+}
+
+func initServer() echoswagger.ApiRoot {
+	e := echo.New()
+
+	se := echoswagger.New(e, "/v2", "doc/", &echoswagger.Info{
+		Title:          "Swagger Petstore",
+		Description:    "This is a sample server Petstore server.  You can find out more about     Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).      For this sample, you can use the api key `special-key` to test the authorization     filters.",
+		Version:        "1.0.0",
+		TermsOfService: "http://swagger.io/terms/",
+		Contact: &echoswagger.Contact{
+			Email: "apiteam@swagger.io",
+		},
+		License: &echoswagger.License{
+			Name: "Apache 2.0",
+			URL:  "http://www.apache.org/licenses/LICENSE-2.0.html",
+		},
+	})
+
+	se.AddSecurityOAuth2("petstore_auth", "", echoswagger.OAuth2FlowImplicit,
+		"http://petstore.swagger.io/oauth/dialog", "", map[string]string{
+			"write:pets": "modify pets in your account",
+			"read:pets":  "read your pets",
+		},
+	).AddSecurityAPIKey("api_key", "", echoswagger.SecurityInHeader)
+
+	se.SetExternalDocs("Find out more about Swagger", "http://swagger.io").
+		SetResponseContentType("application/xml", "application/json").
+		SetUI(echoswagger.UISetting{HideTop: true})
+
+	PetController{}.Init(se.Group("pet", "/pet"))
+	StoreController{}.Init(se.Group("store", "/store"))
+	UserController{}.Init(se.Group("user", "/user"))
+
+	return se
+}

examples/main_test.go

@@ -0,0 +1,25 @@
+package main
+
+import (
+	"io/ioutil"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/elvinchan/echoswagger"
+	"github.com/labstack/echo"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestMain(t *testing.T) {
+	e := initServer()
+	req := httptest.NewRequest(echo.GET, "/doc/swagger.json", nil)
+	rec := httptest.NewRecorder()
+	c := e.Echo().NewContext(req, rec)
+	b, err := ioutil.ReadFile("./swagger.json")
+	assert.Nil(t, err)
+	if assert.NoError(t, e.(*echoswagger.Root).Spec(c)) {
+		assert.Equal(t, http.StatusOK, rec.Code)
+		assert.JSONEq(t, string(b), rec.Body.String())
+	}
+}