Integrating Swagger with Yapi for Automated API Documentation in Go

Both front‑end and back‑end developers often suffer from outdated or missing API documentation. This article presents a method to bridge Swagger and Yapi so that API docs are generated automatically from code comments.

1. Swagger Overview

Swagger is a complete framework for describing, generating, and visualising RESTful APIs. By writing Swagger annotations in the source code, you can generate JSON/YAML specifications, client/server code, and an interactive UI.

2. Setting Up Swagger in a Go Environment

Assuming a working Go environment, install go‑swagger:

mkdir DownLoad
cd DownLoad
git clone https://github.com/go-swagger/go-swagger
cd DownLoad/go-swagger-master/cmd/swagger/
go install .

Verify the installation:

[work@host /]$ swagger -h
Usage: swagger [OPTIONS]
Available commands: diff, expand, flatten, generate, init, mixin, serve, validate, version

3. Swagger Annotations

Key annotation types:

// swagger:meta – API overview (must be placed directly before the package statement with no blank line).

// swagger:route [METHOD] [PATH] [TAG] [OPERATION_ID] – Describes a single endpoint.

// swagger:parameters [OPERATION_ID] – Defines request parameters (e.g., in: query , in: formData ).

// swagger:response [RESPONSE_NAME] – Defines the response body; the struct must contain a nested Body struct for in: body handling.

// swagger:model – An alternative to swagger:response that avoids the extra Body wrapper.

Example of a GET endpoint with parameters:

// ServeAPI serves the API for this record store
func ServeAPI(host, basePath string, schemes []string) error {
// swagger:route GET /{id}/checkout SwaggerTest swagger_test_checkout
// Swagger test endpoint
// Consumes: multipart/form-data
// Responses: 200: old_api_resp
mountItem("GET", basePath+"/{id}/checkout", nil)
}

Parameter definition (GET):

// swagger:parameters swagger_test_checkout
type SwaggerTest struct {
// ID of the item (required)
// in: query
ID uint64 `json:"id"`
}

Response definition (using swagger:response ):

// swagger:response validationError
type ValidationError struct {
// in: body
Body struct {
Message   string `json:"message"`
FieldName string `json:"fieldName,omitempty"`
}
}

Alternatively, using swagger:model to avoid the extra Body wrapper:

// swagger:model old_api_resp
type OldAPIRes struct {
ID   uint64
Name string
Time string
}

4. Generating the Swagger Specification

Run the generator after annotating the code:

swagger generate spec -o ./swagger.json

For model‑only scanning:

swagger generate spec -m -o ./swagger.json

5. Exposing swagger.json via Nginx

Install and start Nginx, then add a server block to serve the generated JSON:

sudo yum install nginx -y
sudo systemctl start nginx
# /etc/nginx/conf.d/yapi.conf
server {
listen 8888;
server_name localhost;
location /data/ {
alias "/home/work/Swagger/swagger-yapi/swagger-json/";
}
}
sudo systemctl restart nginx

Now http:// your‑ip :8888/data/swagger.json can be used as the import URL for Yapi.

6. Importing into Yapi

Manual import – upload the JSON file.

Automatic import – configure Yapi to fetch the JSON from the Nginx endpoint, enabling real‑time synchronization whenever the Swagger spec is regenerated.

With this pipeline, developers only need to update the Swagger comments; the documentation on Yapi stays in sync without extra effort.

7. Conclusion

The article demonstrates a practical workflow that combines Swagger’s code‑first documentation generation with Yapi’s powerful API management features. By automating the bridge, teams reduce manual documentation work, avoid version drift, and keep both front‑end and back‑end developers aligned.