Golang using Beego + swagger to build better API services

API code and document synchronization

From the Go code comment to the Generate Swagger.json service description document, the functionality of the Beego framework is used, which parse the comments in the code-specific format, generating a documentation that conforms to the SWARGERV2.0 specification.

Comments in Routers/router.go, corresponding to the content of the production:

@APIVersion 1.0.0
//@Title horizon-robotics deep-learning-uni-api-server
//@Description Documents of Server API powered by swagger, you can also generate client code by swagger. Refer:https://github.com/swagger-api/swagger-codegen
//@Contact ming.zhao@hobot.cc
//@TermsOfServiceUrl http://www.horizon.ai/
//@License Apache 2.0
//@LicenseUrl http://www.apache.org/licenses/LICENSE-2.0.html

Comments in the Controller

@Title get 1 Job ' s detail info
//@Description Get 1 job ' s detail info
//@Param AppID body String true "your A Ppid "
//@Param Appkey body String true" your Appkey "
//@Param job_id body string true" unique job id:eg. mobilenetres0.75_norm_1501205873 "
//@Success $ {Object} models. Jobinfo "OK"
//@Failure {object} models. Retobj "Paras Missing"
//@Failure {object} models. Retobj "Do not has this job"
//@router/get-job-detail [post]
func (c *jobquerycontroller) Getdetail () {...
}

Corresponds to the generated content

As soon as you modify the code, you can use the Bee run-downdoc=true-gendoc=true to get the latest API documentation and manually "try it out" as long as you are sure that the annotations are updated synchronously.

Swagger and OPENAPI specifications

We are currently using the V2 version, with its specification details such as links. A better understanding of the visual version of the following diagram, the most important part of the composition has been given:

The original intention of the Swagger project was to give the ability to create service-side and client-code, respectively, for the product's rapid prototyping, by simply writing the service documentation for the agreed specifications. Swagger.json can be handwritten, or you can use a dedicated editor.

After reading this tutorial, you will be able to write the documentation of the specification in a more proficient state.

Writing-openapi-swagger-specification-tutorial

Production Client Code

The Client SDK code logic that invokes the API service is actually similar, except that different languages and running devices require different implementations. Also, if the API has minor tweaks, multiple versions of the SDK need to be modified separately, which is inconvenient for maintenance. Now, based on the Swagger.json generated by Go code synchronization, it is fast and easy to generate SDK code in multiple languages at once.

 

	

  
#!/bin/bash
 #in mac, use brew install swagger-codegen.
 #refer:https://github.com/swagger-api/swagger-codegen Available languages: [akka-scala, android, apache2, apex, aspnet5, aspnetcore, async-scala, bash, csharp, clojure, cwiki, cpprest, CsharpDotNet2, dart, elixir, eiffel, erlang-server, finch, flash, python-flask, go, go-server, groovy, haskell, jmeter, jaxrs-cxf-client, jaxrs-cxf, java, inflector, jaxrs-cxf-cdi, jaxrs-spec, jaxrs, msf4j, java-play-framework, jaxrs-resteasy-eap, jaxrs-resteasy, javascript, javascript-closure-angular, java-vertx, kotlin, lumen, nancyfx, nodejs-server, objc, perl, php, php-symfony, powershell, pistache-server, python, qt5cpp, rails5, restbed, ruby, scala, scalatra, silex-PHP, sinatra, slim, spring, dynamic-html, html2, html, swagger, swagger-yaml, swift4, swift3, swift, tizen, typescript-angular2, typescript-angular, typescript-fetch, typescript-jquery, typescript-node, undertow, ze-ph]
 swagger-codegen generate  -i http://petstore.swagger.io/v2/swagger.json -l php -o ./gencode


  


 

As a command, the SDK code for PHP calls will be generated based on Http://petstore.swagger.io/v2/swagger.json