Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added redocly UI theme #117

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open

Added redocly UI theme #117

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
90daa4c
Add files via upload
mudphilo Dec 14, 2023
0832d35
added redocly ui theme
Dec 14, 2023
548eb57
Merge branch 'master' of github.com:mudphilo/echo-swagger
Dec 14, 2023
0f61a14
added redocly ui theme
Dec 14, 2023
34b8eff
fixed failing tests
Dec 16, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,3 +87,46 @@ e.Use(middleware.GzipWithConfig(middleware.GzipConfig{
},
}))
```

### Change UI Theme to redocly:

You can use [redocly open sourceapi theme](https://redocly.com/docs/redoc/deployment/html/) to style up your user interface, to use this pass the theme name when you create your route

```go
package main

import (
"github.com/labstack/echo/v4"
"github.com/swaggo/echo-swagger"

_ "github.com/swaggo/echo-swagger/example/docs" // docs is generated by Swag CLI, you have to import it.
)

// @title Swagger Example API
// @version 1.0
// @description This is a sample server Petstore server.
// @termsOfService http://swagger.io/terms/

// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email [email protected]

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host petstore.swagger.io
// @BasePath /v2
func main() {
e := echo.New()

// pass theme name as redocly
e.GET("/swagger/*", echoSwagger.EchoWrapHandler(echoSwagger.ThemeName("redocly")))

e.Logger.Fatal(e.Start(":1323"))
}

```

5. Run it, and browser to http://localhost:1323/swagger/index.html, you can see Swagger 2.0 Api documents.

![swagger_index.html](https://raw.githubusercontent.com/mudphilo/echo-swagger/90daa4cf6fbde73190e7b6e88851ca467355cedb/Screenshot%202023-12-15%20at%2002.46.10.png)
209 changes: 207 additions & 2 deletions example/docs/docs.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ package docs
import "github.com/swaggo/swag"

const docTemplate_swagger = `{
"schemes": {{ marshal .Schemes }},
"schemes": {{ marshal .Schemes }},
"swagger": "2.0",
"info": {
"description": "{{escape .Description}}",
Expand All @@ -24,7 +24,212 @@ const docTemplate_swagger = `{
},
"host": "{{.Host}}",
"basePath": "{{.BasePath}}",
"paths": {}
"paths": {
"/file/upload": {
"post": {
"description": "Upload file",
"consumes": [
"multipart/form-data"
],
"produces": [
"application/json"
],
"tags": [
"Upload File"
],
"summary": "Upload file",
"operationId": "file.upload",
"parameters": [
{
"type": "file",
"description": "this is a test file",
"name": "file",
"in": "formData",
"required": true
}
],
"responses": {
"200": {
"description": "ok",
"schema": {
"type": "string"
}
},
"400": {
"description": "We need ID!!",
"schema": {
"type": "object",
"$ref": "#/definitions/web.APIError"
}
},
"404": {
"description": "Can not find ID",
"schema": {
"type": "object",
"$ref": "#/definitions/web.APIError"
}
}
}
}
},
"/testapi/get-string-by-int/{some_id}": {
"get": {
"description": "get string by ID",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Upload File"
],
"summary": "Add a new pet to the store",
"operationId": "get-string-by-int",
"parameters": [
{
"type": "int",
"description": "Some ID",
"name": "some_id",
"in": "path",
"required": true
},
{
"description": "Some ID",
"name": "some_id",
"in": "body",
"required": true,
"schema": {
"type": "object",
"$ref": "#/definitions/web.Pet"
}
}
],
"responses": {
"200": {
"description": "ok",
"schema": {
"type": "string"
}
},
"400": {
"description": "We need ID!!",
"schema": {
"type": "object",
"$ref": "#/definitions/web.APIError"
}
},
"404": {
"description": "Can not find ID",
"schema": {
"type": "object",
"$ref": "#/definitions/web.APIError"
}
}
}
}
},
"/testapi/get-struct-array-by-string/{some_id}": {
"get": {
"description": "get struct array by ID",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Upload File"
],
"operationId": "get-struct-array-by-string",
"parameters": [
{
"type": "string",
"description": "Some ID",
"name": "some_id",
"in": "path",
"required": true
},
{
"type": "int",
"description": "Offset",
"name": "offset",
"in": "query",
"required": true
},
{
"type": "int",
"description": "Offset",
"name": "limit",
"in": "query",
"required": true
}
],
"responses": {
"200": {
"description": "ok",
"schema": {
"type": "string"
}
},
"400": {
"description": "We need ID!!",
"schema": {
"type": "object",
"$ref": "#/definitions/web.APIError"
}
},
"404": {
"description": "Can not find ID",
"schema": {
"type": "object",
"$ref": "#/definitions/web.APIError"
}
}
}
}
}
},
"definitions": {
"web.APIError": {
"type": "object",
"properties": {
"CreatedAt": {
"type": "string",
"format": "date-time"
},
"ErrorCode": {
"type": "integer"
},
"ErrorMessage": {
"type": "string"
}
}
},
"web.Pet": {
"type": "object",
"properties": {
"Category": {
"type": "object"
},
"ID": {
"type": "integer"
},
"Name": {
"type": "string"
},
"PhotoUrls": {
"type": "array"
},
"Status": {
"type": "string"
},
"Tags": {
"type": "array"
}
}
}
}
}`

// SwaggerInfo_swagger holds exported Swagger Info so clients can modify it
Expand Down
1 change: 1 addition & 0 deletions example/main.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ func main() {
e := echo.New()

e.GET("/swagger/*", echoSwagger.WrapHandler)
e.GET("/swagger/redocly/*", echoSwagger.EchoWrapHandler(echoSwagger.ThemeName("redocly")))

/*
Or can use EchoWrapHandler func with configurations.
Expand Down
Binary file added redocly-theme-screenshot.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
62 changes: 61 additions & 1 deletion swagger.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,9 @@ type Config struct {

// The information for OAuth2 integration, if any.
OAuth *OAuthConfig

// Information abouth theme, default theme is swagger-ui
Theme string
}

// OAuthConfig stores configuration for Swagger UI OAuth2 integration. See
Expand Down Expand Up @@ -82,6 +85,13 @@ func InstanceName(instanceName string) func(*Config) {
}
}

// ThemeName specified swag theme name.
func ThemeName(themeName string) func(*Config) {
return func(c *Config) {
c.Theme = themeName
}
}

// PersistAuthorization Persist authorization information over browser close/refresh.
// Defaults to false.
func PersistAuthorization(persistAuthorization bool) func(*Config) {
Expand Down Expand Up @@ -115,6 +125,11 @@ func newConfig(configFns ...func(*Config)) *Config {
config.InstanceName = swag.Name
}

// if theme is black set default theme to swagger ui
if config.Theme == "" {
config.Theme = "swagger-ui"
}

return &config
}

Expand All @@ -126,8 +141,19 @@ func EchoWrapHandler(options ...func(*Config)) echo.HandlerFunc {
config := newConfig(options...)

// create a template with name
index, _ := template.New("swagger_index.html").Parse(indexTemplate)

var index *template.Template

// create a template with name
if config.Theme == "redocly" {

index, _ = template.New("swagger_index.html").Parse(redoclyIndexTemplate)

} else {

index, _ = template.New("swagger_index.html").Parse(indexTemplate)

}
var re = regexp.MustCompile(`^(.*/)([^?].*)?[?|.]*$`)

return func(c echo.Context) error {
Expand Down Expand Up @@ -309,3 +335,37 @@ window.onload = function() {

</html>
`

const redoclyIndexTemplate = `<!-- HTML for static distribution bundle build -->
<!DOCTYPE html>
<html lang="en">
<head>
<title>API Documentation</title>
<!-- needed for adaptive design -->
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link
href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700"
rel="stylesheet"
/>

<!--
Redoc doesn't change outer page styles
-->
<style>
body {
margin: 0;
padding: 0;
}
</style>
</head>

<body id="{{.DomID}}">

<redoc spec-url="./doc.json"></redoc>
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>

</body>

</html>
`
13 changes: 13 additions & 0 deletions swagger_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -277,6 +277,19 @@ func TestWrapHandler(t *testing.T) {

}

func TestWrapHandlerWithRedoclyTheme(t *testing.T) {
router := echo.New()

router.Any("/*", EchoWrapHandler(DocExpansion("none"), DomID("swagger-ui"), ThemeName("redocly")))

w1 := performRequest(http.MethodGet, "/index.html", router)
assert.Equal(t, http.StatusOK, w1.Code)
assert.Equal(t, w1.Header()["Content-Type"][0], "text/html; charset=utf-8")

assert.Equal(t, http.StatusInternalServerError, performRequest(http.MethodGet, "/doc.json", router).Code)

}

func TestConfig(t *testing.T) {
router := echo.New()

Expand Down