2. Being a developer, you might understand
how important it is to document and
organize all the APIs, and you also know not
every developer likes this documentation
part. For that, we need some tools that can
be easily used to prepare API
documentation. Well, the very first tool that
strikes is Swagger.
4. Swagger is a set of open-source tools for
writing REST-based APIs. It simplifies the
process of writing APIs by notches,
specifying the standards & providing the
tools required to write and organize
scalable APIs.
6. As mentioned before, when we have to
follow methodology, documentations are a
‘must.’ With swagger, we can create API
documentation by just adding comments in
code.
Now the question might strike Is Swagger
just for API documentation? No, it’s not.
With Swagger, we can generate clients for
any technologies like Node, AngularJS, PHP,
and many more. Thus, it is good for naming
conventions, maintaining best practices,
and common structure for our application.
Also, it does save coding time on the client
side.
Now, let’s see what we will do in this
tutorial.
8. In this tutorial, we will make a demo
application and prepare API documentation
using go-swagger. Watch the video below to
have a look at what we are going to build in
this tutorial.
10. Without further ado, let’s get started with
the coding part. Here are the step-by-step
instructions to create Golang API
documentation.
Create Project Directory
Use the below commands to create a project
directory.
mkdir goswagger
cd goswagger
go mod init goswagger
12. Mux: Handling http requests and
routing
Command:
go get github.com/gorilla/mux
Swagger: Handling swagger doc
Command:
go get github.com/go-
openapi/runtime/middleware
MySQL: Handling MySQL queries
Commands:
github.com/go-sql-driver/mysql
go get github.com/jmoiron/sqlx
13. Import Database
company.sql from the Root
Directory
Create main.go in the root directory.
Establish database connection, routing for
APIs, and Swagger documentation.
r := mux.NewRouter()
dbsqlx := config.ConnectDBSqlx()
hsqlx :=
controllers.NewBaseHandlerSqlx(dbsqlx)
company :=
r.PathPrefix("/admin/company").Subrouter()
company.HandleFunc("/",
hsqlx.PostCompanySqlx).Methods("POST")
company.HandleFunc("/",
hsqlx.GetCompaniesSqlx).Methods("GET")
company.HandleFunc("/{id}",
hsqlx.EditCompany).Methods("PUT")
company.HandleFunc("/{id}",
hsqlx.DeleteCompany).Methods("DELETE")
14. Write Documentation using
Go Swagger
Now, let’s see how to document using
Swagger. It will consist of basic
configurations, models, and API routes.
Basic Configuration
// Comapany Api:
// version: 0.0.1
// title: Comapany Api
// Schemes: http, https
// Host: localhost:5000
// BasePath: /
// Produces:
// - application/json
//
// securityDefinitions:
// apiKey:
// type: apiKey
// in: header
// name: authorization
// swagger:meta
package controllers
15. For security definition, we can use the API
key, which can be verified for every API.
Models
Create models for requests and responses
for our APIs. Below are some examples of
structure with swagger comments. We can
add name, type, schema, required, and
description for every field.
type ReqAddCompany struct {
// Name of the company
// in: string
Name string
`json:"name"validate:"required,min=2,max=
100,alpha_space"`
// Status of the company
// in: int64
Status int64 `json:"status"
validate:"required"`
}
16. // swagger:parameters admin addCompany
type ReqCompanyBody struct {
// - name: body
// in: body
// description: name and status
// schema:
// type: object
// "$ref": "#/definitions/ReqAddCompany"
// required: true
Body ReqAddCompany `json:"body"`
}
// swagger:model Company
type Company struct {
// Id of the company
// in: int64
Id int64 `json:"id"`
// Name of the company
// in: string
Name string `json:"name"`
// Status of the company
// in: int64
Status int64 `json:"status"`
}
17. // swagger:model CommonError
type CommonError struct {
// Status of the error
// in: int64
Status int64 `json:"status"`
// Message of the error
// in: string
Message string `json:"message"`
}
API Routes
We can add swagger comments for every
route. In which we can specify request and
response models, route name, the request
method, description, and API key if
required.
24. // security:
// - apiKey: []
// responses:
// 401: CommonError
// 200: CommonSuccess
// Create handles Delete get company
func (h *BaseHandlerSqlx)
DeleteCompany(w http.ResponseWriter, r
*http.Request) {
vars := mux.Vars(r)
errmessage := models.DeleteCompany(h.db,
vars["id"])
if errmessage != "" {
json.NewEncoder(w).Encode(ErrHandler(er
rmessage))
return
}
successresponse := CommonSuccess{}
25. successresponse.Status = 1
successresponse.Message =
lang.Get("delete_success")
w.Header().Set("content-type",
"application/json")
json.NewEncoder(w).Encode(successrespon
se)
}
After done with api, we can generate
swagger yaml or JSON files from swagger
comments using the below command in the
root directory.
swagger generate spec -o ./swagger.yaml –
scan-models
26. It will generate a swagger.yaml file in the
root directory. We can also create a JSON
file the same way.
Using this file, we can add routes for
documentation in the main.go file.
// documentation for developers
opts :=
middleware.SwaggerUIOpts{SpecURL:
"/swagger.yaml"}
sh := middleware.SwaggerUI(opts, nil)
r.Handle("/docs", sh)
// documentation for share
// opts1 :=
middleware.RedocOpts{SpecURL:
"/swagger.yaml"}
// sh1 := middleware.Redoc(opts1, nil)
// r.Handle("/docs", sh1)
27. Once you are done with the steps,
documentation for developers will look
something like the below images.
Refer to the below documentation for Read-
Only APIs that you want to share with
external developers.
30. As mentioned above in the beginning,
Swagger isn’t just for API documentation;
we can also generate clients using Swagger.
Let’s see the below example for client
generation for AngularJS.
Example: Client Generation for AngularJS.
npm install ng-swagger-gen --save-dev
sudo node_modules/.bin/ng-swagger-gen -i
../swagger.yaml -o backend/src/app
It will create services files for all the APIs
that are to be included in the Swagger
document. In the same way, you can
generate clients for other frameworks and
technologies.
31. So, this was about creating Golang API
Documentation using go-swagger. For
complete documentation, please feel free to
visit the github repository: go-swagger-
example
33. I hope the Go Swagger tutorial was helpful
to you and has cleared your doubts
regarding Swagger Documentation for
Golang APIs. If you are a Golang enthusiast,
please visit the Golang Tutorials page for
more such tutorials and start learning more
each day! Feel free to drop comments and
connect in case you have any questions.
Sometimes many requirements demand
skilled, knowledgeable, and dedicated
developers for their Golang projects. For
such requirements, it is advisable to contact
and hire proficient developers. Are you
looking for such developers for your
projects too? If yes, then why waste time?
Contact Bacancy immediately to hire
Golang developers with fundamental and
advanced Golang knowledge.