Swagno: no annotations, no files, no commands

Swagno redefines the way API documentation is created, embedding documentation seamlessly into your codebase for a clutter-free, streamlined experience. This tool does away with the hassles of annotations, exported files, and command executions. Simplify your documentation process with Swagno. Embrace the ease: Swagno - no annotations, no exports, no commands!

🚀 Now supports both Swagger 2.0 and OpenAPI 3.0!

About the Project

This project inspired by Swaggo. Swaggo, uses annotations, exports files and needs to run by command. If you don't like this way, Swagno appears as a good alternative.

Versions

Swagno supports both specification versions:

• v2 (default): Swagger 2.0 specification - Use the main package github.com/go-swagno/swagno
• v3: OpenAPI 3.0.3 specification - Use the v3 package github.com/go-swagno/swagno/v3

OpenAPI 3.0 Support 🆕

Starting with v3, Swagno now supports OpenAPI 3.0.3 specification with enhanced features:

// OpenAPI 3.0 usage
import swagno3 "github.com/go-swagno/swagno/v3"

openapi := swagno3.New(swagno3.Config{
    Title:   "My API",
    Version: "v1.0.0",
})
openapi.AddServer("https://api.example.com/v1", "Production server")
openapi.SetBearerAuth("JWT", "Bearer authentication")

New OpenAPI 3.0 Features:

• ✅ Multiple servers support
• ✅ Enhanced security schemes (Bearer, OpenID Connect)
• ✅ Proper request body handling with content types
• ✅ Improved schema definitions with nullable, readOnly, writeOnly
• ✅ Better parameter validation and examples
• ✅ Components-based architecture

📖 See v3 documentation for detailed OpenAPI 3.0 usage and migration guide.

Contents

• Examples
• Getting started
• Supported Web Frameworks
• Implementation Status
• Create Your Swagger
  • General Swagger Info
  • Endpoints (API)
    • Endpoint Options
  • Parameters
    • Parameter Location
    • Parameter Types
    • Parameter Options
  • Defining Models
  • Security
• Contribution

Getting started

0. Server Example here

1. Get swagno package in your project

go get github.com/go-swagno/swagno

2. Import swagno

import "github.com/go-swagno/swagno"
import "github.com/go-swagno/swagno-http/swagger" // recommended if you want to use go-swagno http handler for serving swagger docs

3. Create your endpoints (check Endpoints) with it's corresponding parameters. Example:

 endpoints := []*endpoint.EndPoint{
  endpoint.New(
    endpoint.GET,
    "/product/page",
    endpoint.WithTags("product"),
    endpoint.WithSuccessfulReturns([]response.Response{response.New(models.EmptySuccessfulResponse{}, "OK", "200")}),
    endpoint.WithErrors([]response.Response{response.New(models.UnsuccessfulResponse{}, "Bad Request", "400")}),
    endpoint.WithDescription(desc),
    endpoint.WithProduce([]mime.MIME{mime.JSON, mime.XML}),
    endpoint.WithConsume([]mime.MIME{mime.JSON}),
  ),
  endpoint.New(
    endpoint.GET,
    "/product",
    endpoint.WithTags("product"),
    endpoint.WithParams(parameter.IntParam("id", parameter.WithRequired())),
    endpoint.WithSuccessfulReturns([]response.Response{response.New(models.EmptySuccessfulResponse{}, "OK", "200")}),
    endpoint.WithErrors([]response.Response{response.New(models.UnsuccessfulResponse{}, "Bad Request", "400")}),
  ),
  endpoint.New(
    endpoint.GET,
    "/product/{id}/detail",
    endpoint.WithTags("product"),
    endpoint.WithParams(parameter.IntParam("id", parameter.WithRequired())),
    endpoint.WithSuccessfulReturns([]response.Response{response.New(models.EmptySuccessfulResponse{}, "OK", "200")}),
    endpoint.WithErrors([]response.Response{response.New(models.UnsuccessfulResponse{}, "Bad Request", "400")}),
  ),
  endpoint.New(
    endpoint.POST,
    "/product",
    endpoint.WithTags("product"),
    endpoint.WithBody(models.ProductPost{}),
    endpoint.WithSuccessfulReturns([]response.Response{response.New(models.EmptySuccessfulResponse{}, "OK", "200")}),
    endpoint.WithErrors([]response.Response{response.New(models.UnsuccessfulResponse{}, "Bad Request", "400")}),
    endpoint.WithProduce([]mime.MIME{mime.JSON, mime.XML}),
  ),
}

4. Create Swagger(swagno) instance

sw := swagno.New(swagno.Config{Title: "Testing API", Version: "v1.0.0", Host: "localhost:8080"})

5. Use sw.AddEndpoints function to add endpoints arrays to Swagno

sw.AddEndpoints(endpoints)

// you can also add more arrays
sw.AddEndpoints(productEndpoints)
sw.AddEndpoints(merchantEndpoints)

6. Generate json as string and give it to your handler to serve. You can create your own handler or use the swagno http handler

 http.HandleFunc("/swagger/", swagger.SwaggerHandler(sw.MustToJson()))
 fmt.Println("Server is running on http://localhost:8080")
 http.ListenAndServe(":8080", nil)

Supported Web Frameworks

• fiber
• gin
• gorilla/mux
• net/http

How to use with Fiber

You can read detailed document and find better examples in swagno-fiber

Example:

1. Get swagno-fiber

go get github.com/go-swagno/swagno-fiber

2. Import swagno-fiber

import "github.com/go-swagno/swagno-fiber/swagger"

...
// assume you declare your endpoints and "sw"(swagno) instance
swagger.SwaggerHandler(a, sw.MustToJson(), swagger.WithPrefix("/swagger"))
...

You can find a detailed example in https://github.com/go-swagno/swagno/example/fiber

How to use with Gin

You can read detailed document and find better examples in swagno-gin

Example:

1. Get swagno-gin

go get github.com/go-swagno/swagno-gin

2. Import swagno-gin

import "github.com/go-swagno/swagno-gin/swagger"

...
// assume you declare your endpoints and "sw"(swagno) instance
a.GET("/swagger/*any", swagger.SwaggerHandler(sw.MustToJson()))
...

You can find a detailed example in https://github.com/go-swagno/swagno/example/gin

Implementation Status

As purpose of this section, you can compare swagno status with swaggo

Swagger 2.0 document

See how Swagno compares to Swaggo in terms of Swagger 2.0 features:

• Basic Structure: ✅
• API Host and Base Path: ✅
• Paths and Operations: ✅
• Describing Parameters: ✅
• Describing Request Body: ✅
• Describing Responses: ✅
• MIME Types: 🔄 (Improvement needed)
• Authentication: ✅
• File Upload: 🔄 (Improvement needed)
• Enums: ✅
• Grouping Operations With Tags: ✅
• Swagger Extensions: 🔜 (Coming soon)
• Swagger Validation: 🔜 (Coming soon)

Create Your Swagger

General Swagger Info

Swagger v2.0 specifications can be found here

You can use the swagger config when creating new swagger object

type Config struct {
  Title          string   // title of the Swagger documentation
  Version        string   // version of the Swagger documentation
  Description    string   // description of the Swagger documentation
  Host           string   // host URL for the API
  Path           string   // path to the Swagger JSON file
  License        *License // license information for the Swagger documentation
  Contact        *Contact // contact information for the Swagger documentation
  TermsOfService string   // term of service information for the Swagger documentation
}

sw := swagno.New(swagno.Config{Title: "Testing API", Version: "v1.0.0", Host: "localhost:8080"}) // optionally you can also use the License and Info properties as well

Endpoints (API)

Definition:

type EndPoint struct {
 method            string
 path              string
 params            []*parameter.Parameter
 tags              []string
 Body              interface{}
 successfulReturns []response.Info
 errors            []response.Info
 description       string
 summary           string
 consume           []mime.MIME
 produce           []mime.MIME
 security          []map[string][]string
}

You need to create an Endpoint array []Endpoint and add your endpoints in this array. Example:

import "github.com/go-swagno/swagno/components/endpoint"

endpoints := []*endpoint.EndPoint{
  endpoint.New(
    endpoint.POST,
    "/product",
    endpoint.WithTags("product"),
    endpoint.WithBody(models.ProductPost{}),
    endpoint.WithSuccessfulReturns([]response.Info{models.SuccessfulResponse{}}),
    endpoint.WithErrors([]response.Info{models.UnsuccessfulResponse{}}),
    endpoint.WithProduce([]mime.MIME{mime.JSON, mime.XML}),
  ),
}
// add endpoints array to Swagno
sw.AddEndpoints(endpoints)

Note: You can simply add only one endpoint by using AddEndpoint(endpoint)

Endpoint Options

Arguments: The EndPoint object is configured via the With<property> functional options provided in the github.com/go-swagno/swagno/components/endpoint package

| Function | Description