swag
v1.16.4
؟ اللغة الإنجليزية ∙ ∙ português
يحول SWAG التعليقات التوضيحية إلى Swagger Docager 2.0. لقد أنشأنا مجموعة متنوعة من المكونات الإضافية لأطر الويب الشهيرة GO. يتيح لك ذلك الاندماج بسرعة مع مشروع GO الحالي (باستخدام Swagger UI).
أضف تعليقات إلى رمز مصدر API الخاص بك ، راجع تنسيق التعليقات التعريفية.
تثبيت غنيمة باستخدام:
go install github.com/swaggo/swag/cmd/swag@latestللبناء من المصدر الذي تحتاجه GO (1.19 أو أحدث).
بدلاً من ذلك ، يمكنك تشغيل صورة Docker:
docker run --rm -v $( pwd ) :/code ghcr.io/swaggo/swag:latestأو قم بتنزيل ثنائي مسبقًا من صفحة الإصدار.
swag init في مجلد الجذر للمشروع الذي يحتوي على ملف main.go سيؤدي ذلك إلى تحليل تعليقاتك وإنشاء الملفات المطلوبة (مجلد docs docs/docs.go ). swag init تأكد من استيراد docs/docs.go تم إنشاؤها بحيث init تكوينك المحدد. إذا لم تعيش تعليقات API العامة الخاصة بك في main.go ، فيمكنك السماح لـ Swag بمعرفة علم -g .
import _ "example-module-name/docs" swag init -g http/api.goswag fmt تعليق SWAG. (يرجى الترقية إلى أحدث إصدار) swag fmtswag init -h
NAME:
swag init - Create docs.go
USAGE:
swag init [command options] [arguments...]
OPTIONS:
--quiet, -q Make the logger quiet. (default: false)
--generalInfo value, -g value Go file path in which ' swagger general API Info ' is written (default: " main.go " )
--dir value, -d value Directories you want to parse,comma separated and general-info file must be in the first one (default: " ./ " )
--exclude value Exclude directories and files when searching, comma separated
--propertyStrategy value, -p value Property Naming Strategy like snakecase,camelcase,pascalcase (default: " camelcase " )
--output value, -o value Output directory for all the generated files(swagger.json, swagger.yaml and docs.go) (default: " ./docs " )
--outputTypes value, --ot value Output types of generated files (docs.go, swagger.json, swagger.yaml) like go,json,yaml (default: " go,json,yaml " )
--parseVendor Parse go files in ' vendor ' folder, disabled by default (default: false)
--parseDependency, --pd Parse go files inside dependency folder, disabled by default (default: false)
--parseDependencyLevel, --pdl Enhancement of ' --parseDependency ' , parse go files inside dependency folder, 0 disabled, 1 only parse models, 2 only parse operations, 3 parse all (default: 0)
--markdownFiles value, --md value Parse folder containing markdown files to use as description, disabled by default
--codeExampleFiles value, --cef value Parse folder containing code example files to use for the x-codeSamples extension, disabled by default
--parseInternal Parse go files in internal packages, disabled by default (default: false)
--generatedTime Generate timestamp at the top of docs.go, disabled by default (default: false)
--parseDepth value Dependency parse depth (default: 100)
--requiredByDefault Set validation required for all fields by default (default: false)
--instanceName value This parameter can be used to name different swagger document instances. It is optional.
--overridesFile value File to read global type overrides from. (default: " .swaggo " )
--parseGoList Parse dependency via ' go list ' (default: true)
--tags value, -t value A comma-separated list of tags to filter the APIs for which the documentation is generated.Special case if the tag is prefixed with the ' ! ' character then the APIs with that tag will be excluded
--templateDelims value, --td value Provide custom delimiters for Go template generation. The format is leftDelim,rightDelim. For example: " [[,]] "
--collectionFormat value, --cf value Set default collection format (default: " csv " )
--state value Initial state for the state machine (default: " " ), @HostState in root file, @State in other files
--parseFuncBody Parse API info within body of functions in go files, disabled by default (default: false)
--help, -h show help (default: false)swag fmt -h
NAME:
swag fmt - format swag comments
USAGE:
swag fmt [command options] [arguments...]
OPTIONS:
--dir value, -d value Directories you want to parse,comma separated and general-info file must be in the first one (default: " ./ " )
--exclude value Exclude directories and files when searching, comma separated
--generalInfo value, -g value Go file path in which ' swagger general API Info ' is written (default: " main.go " )
--help, -h show help (default: false)
ابحث عن مثال رمز المصدر هنا.
إنهاء الخطوات في البدء
swag init لإنشاء مستندات Swagger 2.0 ، استيراد الحزم التالية: import "github.com/swaggo/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed filesmain.go : // @title Swagger Example API
// @version 1.0
// @description This is a sample server celler 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 localhost:8080
// @BasePath /api/v1
// @securityDefinitions.basic BasicAuth
// @externalDocs.description OpenAPI
// @externalDocs.url https://swagger.io/resources/open-api/
func main () {
r := gin . Default ()
c := controller . NewController ()
v1 := r . Group ( "/api/v1" )
{
accounts := v1 . Group ( "/accounts" )
{
accounts . GET ( ":id" , c . ShowAccount )
accounts . GET ( "" , c . ListAccounts )
accounts . POST ( "" , c . AddAccount )
accounts . DELETE ( ":id" , c . DeleteAccount )
accounts . PATCH ( ":id" , c . UpdateAccount )
accounts . POST ( ":id/images" , c . UploadAccountImage )
}
//...
}
r . GET ( "/swagger/*any" , ginSwagger . WrapHandler ( swaggerFiles . Handler ))
r . Run ( ":8080" )
}
//... بالإضافة إلى ذلك ، يمكن تعيين بعض معلومات API العامة ديناميكيًا. يقوم docs حزمة الكود التي تم إنشاؤها بتصدير متغير SwaggerInfo الذي يمكننا استخدامه لتعيين العنوان والوصف والنسخة والمضيف والمسار الأساسي برمجيًا. مثال باستخدام الجن:
package main
import (
"github.com/gin-gonic/gin"
"github.com/swaggo/files"
"github.com/swaggo/gin-swagger"
"./docs" // docs is generated by Swag CLI, you have to import it.
)
// @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
func main () {
// programmatically set swagger info
docs . SwaggerInfo . Title = "Swagger Example API"
docs . SwaggerInfo . Description = "This is a sample server Petstore server."
docs . SwaggerInfo . Version = "1.0"
docs . SwaggerInfo . Host = "petstore.swagger.io"
docs . SwaggerInfo . BasePath = "/v2"
docs . SwaggerInfo . Schemes = [] string { "http" , "https" }
r := gin . New ()
// use ginSwagger middleware to serve the API docs
r . GET ( "/swagger/*any" , ginSwagger . WrapHandler ( swaggerFiles . Handler ))
r . Run ()
}controller package controller
import (
"fmt"
"net/http"
"strconv"
"github.com/gin-gonic/gin"
"github.com/swaggo/swag/example/celler/httputil"
"github.com/swaggo/swag/example/celler/model"
)
// ShowAccount godoc
// @Summary Show an account
// @Description get string by ID
// @Tags accounts
// @Accept json
// @Produce json
// @Param id path int true "Account ID"
// @Success 200 {object} model.Account
// @Failure 400 {object} httputil.HTTPError
// @Failure 404 {object} httputil.HTTPError
// @Failure 500 {object} httputil.HTTPError
// @Router /accounts/{id} [get]
func ( c * Controller ) ShowAccount ( ctx * gin. Context ) {
id := ctx . Param ( "id" )
aid , err := strconv . Atoi ( id )
if err != nil {
httputil . NewError ( ctx , http . StatusBadRequest , err )
return
}
account , err := model . AccountOne ( aid )
if err != nil {
httputil . NewError ( ctx , http . StatusNotFound , err )
return
}
ctx . JSON ( http . StatusOK , account )
}
// ListAccounts godoc
// @Summary List accounts
// @Description get accounts
// @Tags accounts
// @Accept json
// @Produce json
// @Param q query string false "name search by q" Format(email)
// @Success 200 {array} model.Account
// @Failure 400 {object} httputil.HTTPError
// @Failure 404 {object} httputil.HTTPError
// @Failure 500 {object} httputil.HTTPError
// @Router /accounts [get]
func ( c * Controller ) ListAccounts ( ctx * gin. Context ) {
q := ctx . Request . URL . Query (). Get ( "q" )
accounts , err := model . AccountsAll ( q )
if err != nil {
httputil . NewError ( ctx , http . StatusNotFound , err )
return
}
ctx . JSON ( http . StatusOK , accounts )
}
//... swag initيمكن تنسيق تعليقات SWAG تلقائيًا ، تمامًا مثل "Go FMT". ابحث عن نتيجة التنسيق هنا.
الاستخدام:
swag fmtاستبعاد المجلد ：
swag fmt -d ./ --exclude ./internal عند استخدام swag fmt ، تحتاج إلى التأكد من أن لديك تعليق مستند للوظيفة لضمان التنسيق الصحيح. ويرجع ذلك إلى تعليقات swag fmt المسافة البادئة مع علامات التبويب ، والتي لا يُسمح بها إلا بعد تعليق مستند قياسي.
على سبيل المثال ، الاستخدام
// ListAccounts lists all existing accounts
//
// @Summary List accounts
// @Description get accounts
// @Tags accounts
// @Accept json
// @Produce json
// @Param q query string false "name search by q" Format(email)
// @Success 200 {array} model.Account
// @Failure 400 {object} httputil.HTTPError
// @Failure 404 {object} httputil.HTTPError
// @Failure 500 {object} httputil.HTTPError
// @Router /accounts [get]
func ( c * Controller ) ListAccounts ( ctx * gin. Context ) {وثيقة Swagger 2.0
مثال celler/main.go
| التعليقات التوضيحية | وصف | مثال |
|---|---|---|
| عنوان | مطلوب. عنوان التطبيق. | //Title Swagger مثال API |
| إصدار | مطلوب. يوفر إصدار تطبيق API. | // @version 1.0 |
| وصف | وصف قصير للتطبيق. | // Description هذا خادم Colter Server عينة. |
| tag.name | اسم العلامة. | // @tag.name هذا هو اسم العلامة |
| tag.description | وصف العلامة | // @tag.description وصف رائع |
| tag.docs.url | عنوان URL للوثائق الخارجية للعلامة | // @tag.docs.url https://example.com |
| tag.docs.description | وصف الوثائق الخارجية للعلامة | // @tag.docs.description أفضل مثال |
| مصطلحات الخدمات | شروط الخدمة لواجهة برمجة التطبيقات. | // termsofservice http://swagger.io/terms/ |
| contact.name | معلومات الاتصال لواجهة برمجة التطبيقات المكشوفة. | // @contact.name API Support |
| Contact.url | عنوان URL يشير إلى معلومات الاتصال. يجب أن يكون في شكل عنوان URL. | // @contact.url http://www.swagger.io/support |
| Contact.email | عنوان البريد الإلكتروني لشخص الاتصال/المنظمة. يجب أن يكون بتنسيق عنوان البريد الإلكتروني. | // @contact.email [email protected] |
| ترخيص | مطلوب. اسم الترخيص المستخدمة في واجهة برمجة التطبيقات. | // @license.name Apache 2.0 |
| ترخيص | عنوان URL للترخيص المستخدم في واجهة برمجة التطبيقات. يجب أن يكون في شكل عنوان URL. | // @license.url http://www.apache.org/licenses/license-2.0.html |
| يستضيف | المضيف (الاسم أو IP) يخدم واجهة برمجة التطبيقات. | // host localhost: 8080 |
| Basepath | المسار الأساسي الذي يتم تقديم API عليه. | // basepath/api/v1 |
| يقبل | قائمة أنواع MIME التي يمكن أن تستهلكها واجهات برمجة التطبيقات. لاحظ أن القبول يؤثر فقط على العمليات مع هيئة طلب ، مثل Post و Put و Patch. يجب أن تكون القيمة كما هو موضح تحت أنواع MIME. | // Accept JSON |
| ينتج | قائمة أنواع MIME التي يمكن أن تنتجها واجهات برمجة التطبيقات. يجب أن تكون القيمة كما هو موضح تحت أنواع MIME. | // Produce JSON |
| Query.Collection.format | المجموعة الافتراضية (Array) Param Format في الاستعلام ، التعداد: CSV ، Multi ، Pipes ، TSV ، SSV. إذا لم يتم تعيينه ، فإن CSV هو الافتراضي. | // @query.collection.format multi |
| مخططات | بروتوكول النقل للعملية التي تفصلها المساحات. | // schemes http https |
| externaldocs.description | وصف المستند الخارجي. | // @externaldocs.description openapi |
| externaldocs.url | عنوان URL للوثيقة الخارجية. | // @externaldocs.url https://swagger.io/resources/open-api/ |
| x-name | يجب أن يبدأ مفتاح التمديد بـ X- واتخاذ قيمة JSON فقط | // @x-example-key {"key": "value"} |
عندما تكون سلسلة قصيرة في الوثائق غير كافية ، أو تحتاج إلى صور وأمثلة رمز وأشياء مثل تلك التي قد ترغب في استخدام أوصاف التمييز. من أجل استخدام أوصاف التخفيض ، استخدم التعليقات التوضيحية التالية.
| التعليقات التوضيحية | وصف | مثال |
|---|---|---|
| عنوان | مطلوب. عنوان التطبيق. | //Title Swagger مثال API |
| إصدار | مطلوب. يوفر إصدار تطبيق API. | // @version 1.0 |
| الوصف | وصف قصير للتطبيق. تم تحليلها من ملف API.MD. هذا بديل لـ @Description | // @description.markdown لا توجد قيمة مطلوبة ، وهذا يوسع الوصف من API.MD |
| tag.name | اسم العلامة. | // @tag.name هذا هو اسم العلامة |
| tag.description.markdown | وصف العلامة هذا هو بديل للعلامة. سيتم قراءة الوصف من ملف يسمى مثل tagname.md | // @tag.description.markdown |
| tag.x-name | يجب أن يبدأ مفتاح التمديد بـ X- واتخاذ قيمة السلسلة فقط | // @x-example-key value |
مثال celler/وحدة التحكم
| التعليقات التوضيحية | وصف |
|---|---|
| وصف | تفسير مطول لسلوك العملية. |
| الوصف | وصف قصير للتطبيق. سيتم قراءة الوصف من ملف. @description.markdown details سيتم تحميل details.md |
| بطاقة تعريف | سلسلة فريدة تستخدم لتحديد العملية. يجب أن تكون فريدة بين جميع عمليات API. |
| العلامات | قائمة العلامات بكل عملية API مفصولة بفواصل. |
| ملخص | ملخص قصير لما تفعله العملية. |
| يقبل | قائمة أنواع MIME التي يمكن أن تستهلكها واجهات برمجة التطبيقات. لاحظ أن القبول يؤثر فقط على العمليات مع هيئة طلب ، مثل Post و Put و Patch. يجب أن تكون القيمة كما هو موضح تحت أنواع MIME. |
| ينتج | قائمة أنواع MIME التي يمكن أن تنتجها واجهات برمجة التطبيقات. يجب أن تكون القيمة كما هو موضح تحت أنواع MIME. |
| بارام | المعلمات التي تفصل عن المسافات. param name ، param type ، data type ، is mandatory? ، سمة comment attribute(optional) |
| حماية | الأمن لكل عملية API. |
| نجاح | استجابة النجاح التي تفصلها المساحات. return code or default ، {param type} ، data type ، comment |
| فشل | استجابة الفشل التي تفصل عن المسافات. return code or default ، {param type} ، data type ، comment |
| إجابة | مثل success failure |
| رأس | رأس استجابة مفصولة بالمساحات. return code ، {param type} ، data type ، comment |
| جهاز التوجيه | تعريف المسار الذي يفصل بين المساحات. path ، [httpMethod] |
| deprecatedrouter | مثل جهاز التوجيه ، ولكن تم إهماله. |
| x-name | يجب أن يبدأ مفتاح التمديد بواسطة X- واتخاذ قيمة JSON فقط. |
| X-Codesample | استخدام تخفيض اختياري. خذ file كمعلمة. سيبحث هذا بعد ذلك عن ملف يسمى مثل الملخص في المجلد المحدد. |
| تم إهماله | نقطة نهاية نقطة كما انخفض. |
يقبل swag جميع أنواع MIME التي هي بالتنسيق الصحيح ، أي مطابقة */* . إلى جانب ذلك ، يقبل swag أيضًا الأسماء المستعارة لبعض أنواع MIME على النحو التالي:
| الاسم المستعار | نوع MIME |
|---|---|
| جيسون | التطبيق/JSON |
| XML | النص/xml |
| سهل | نص/عادي |
| HTML | النص/html |
| MPFD | multipart/form-data |
| x-www-form-urlencoded | التطبيق/x-www-form-urlencoded |
| json-api | التطبيق/vnd.api+json |
| json-stream | التطبيق/x-json-stream |
| ثمار الثماني | تطبيق/ثماني الثماني |
| PNG | الصورة/PNG |
| JPEG | Image/JPEG |
| GIF | الصورة/gif |
| التعليقات التوضيحية | وصف | حدود | مثال |
|---|---|---|---|
| SecurityDefinitions.basic | مصادقة أساسية. | // @securityDefinitions.basic basicauth | |
| SecurityDefinitions.Apikey | API مفتاح المصادقة. | في ، الاسم ، الوصف | // @securityDefinitions.Apikey apikeyauth |
| SecurityDefinitions.oauth2.Application | OAUTH2 APPART Auth. | Tokenurl ، النطاق ، الوصف | // @securityDefinitions.oauth2 |
| SecurityDefinitions.oauth2.implicit | OAUTH2 مصادقة ضمنية. | إذن ، النطاق ، الوصف | // @securityDefinitions.oauth2.implicit oauth2Implicit |
| SecurityDefinitions.oauth2.Password | OAUTH2 كلمة مرور AUTH. | Tokenurl ، النطاق ، الوصف | // @SecurityDefinitions.oauth2.Password Oauth2Password |
| SecurityDefinitions.oauth2.AccessCode | OAuth2 Access Code Auth. | Tokenurl ، التفويض ، النطاق ، الوصف | // @SecurityDefinitions.oauth2.AccessCode OAuth2AccessCode |
| شرح المعلمات | مثال |
|---|---|
| في | // in header |
| اسم | // @name إذن |
| رمز | // tokenurl https://example.com/oauth/token |
| إذن | //Authorizationurl https://example.com/oauth/authorize |
| Scope.hoge | // @scop.write منح الكتابة |
| وصف | // description oauth تحمي نقاط نهاية الكيان لدينا |
// @Param enumstring query string false "string enums" Enums(A, B, C)
// @Param enumint query int false "int enums" Enums(1, 2, 3)
// @Param enumnumber query number false "int enums" Enums(1.1, 1.2, 1.3)
// @Param string query string false "string valid" minlength(5) maxlength(10)
// @Param int query int false "int valid" minimum(1) maximum(10)
// @Param default query string false "string default" default(A)
// @Param example query string false "string example" example(string)
// @Param collection query []string false "string collection" collectionFormat(multi)
// @Param extensions query []string false "string collection" extensions(x-example=test,x-nullable)كما أنه يعمل مع حقول الهيكل:
type Foo struct {
Bar string `minLength:"4" maxLength:"16" example:"random string"`
Baz int `minimum:"10" maximum:"20" default:"15"`
Qux [] string `enums:"foo,bar,baz"`
}| اسم الحقل | يكتب | وصف |
|---|---|---|
| التحقق | string | يحدد التحقق من صحة المعلمة. القيم المحتملة هي: required,optional . |
| تقصير | * | يعلن عن قيمة المعلمة التي سيستخدمها الخادم إذا لم يتم توفير أي منها ، على سبيل المثال "عدد" للتحكم في عدد النتائج لكل صفحة قد يكون افتراضيًا إلى 100 إذا لم يتم توفيره من قبل العميل في الطلب. (ملاحظة: "الافتراضي" ليس له معنى للمعلمات المطلوبة.) انظر https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2. على عكس مخطط JSON ، يجب أن تتوافق هذه القيمة مع type المحدد لهذه المعلمة. |
| الحد الأقصى | number | انظر https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2. |
| الحد الأدنى | number | انظر https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3. |
| متعددة | number | انظر https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1. |
| MaxLength | integer | انظر https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1. |
| الطول | integer | انظر https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2. |
| التعداد | [*] | انظر https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1. |
| شكل | string | التنسيق الممتد type المذكور سابقًا. راجع تنسيقات نوع البيانات لمزيد من التفاصيل. |
| CollectionFormat | string | يحدد تنسيق الصفيف إذا تم استخدام صفيف النوع. القيم الممكنة هي:
csv . |
| مثال | * | يعلن عن مثال قيمة المعلمة |
| الامتدادات | string | أضف التمديد إلى المعلمات. |
| اسم الحقل | يكتب | وصف |
|---|---|---|
| نمط | string | انظر https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3. |
| الحد الأقصى | integer | انظر https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2. |
| Minitems | integer | انظر https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3. |
| فريدة من نوعها | boolean | انظر https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4. |
يمكنك إضافة أوصاف تمتد على خطوط متعددة في وصف API العام أو تعريفات الطرق مثل:
// @description This is the first line
// @description This is the second line
// @description And so forth. // @Success 200 {array} model.Account <-- This is a user defined struct. package model
type Account struct {
ID int `json:"id" example:"1"`
Name string `json:"name" example:"account name"`
} يمكنك إعلان بنية استجابة طلبك داخل جسم وظيفة. يجب أن تتبع اتفاقية التسمية <package-name>.<function-name>.<struct-name> .
package main
// @Param request body main.MyHandler.request true "query params"
// @Success 200 {object} main.MyHandler.response
// @Router /test [post]
func MyHandler () {
type request struct {
RequestField string
}
type response struct {
ResponseField string
}
} // JSONResult's data field will be overridden by the specific type proto.Order
@ success 200 { object } jsonresult. JSONResult { data = proto . Order } "desc" type JSONResult struct {
Code int `json:"code" `
Message string `json:"message"`
Data interface {} `json:"data"`
}
type Order struct { //in `proto` package
Id uint `json:"id"`
Data interface {} `json:"data"`
}@ success 200 { object } jsonresult. JSONResult { data = []proto. Order } "desc"
@ success 200 { object } jsonresult. JSONResult { data = string } "desc"
@ success 200 { object } jsonresult. JSONResult { data = [] string } "desc"@ success 200 { object } jsonresult. JSONResult { data1 = string , data2 = [] string , data3 = proto . Order , data4 = []proto. Order } "desc" type DeepObject struct { //in `proto` package
...
}
@ success 200 { object } jsonresult. JSONResult { data1 = proto. Order { data = proto . DeepObject }, data2 = []proto. Order { data = []proto. DeepObject }} "desc" // @Param X-MyHeader header string true "MyHeader must be set for valid response"
// @Param X-API-VERSION header string true "API version eg.: 1.0" // @Success 200 {string} string "ok"
// @failure 400 {string} string "error"
// @response default {string} string "other error"
// @Header 200 {string} Location "/entity/1"
// @Header 200,400,default {string} Token "token"
// @Header all {string} Token2 "token2" /// ...
// @Param group_id path int true "Group ID"
// @Param account_id path int true "Account ID"
// ...
// @Router /examples/groups/{group_id}/accounts/{account_id} [get] /// ...
// @Param group_id path int true "Group ID"
// @Param user_id path int true "User ID"
// ...
// @Router /examples/groups/{group_id}/user/{user_id}/address [put]
// @Router /examples/user/{user_id}/address [put] type Account struct {
ID int `json:"id" example:"1"`
Name string `json:"name" example:"account name"`
PhotoUrls [] string `json:"photo_urls" example:"http://test/image/1.jpg,http://test/image/2.jpg"`
} // @Param email body string true "message/rfc822" SchemaExample(Subject: TestmailrnrnBody Messagern) // Account model info
// @Description User account information
// @Description with user id and username
type Account struct {
// ID this is userid
ID int `json:"id"`
Name string `json:"name"` // This is Name
} #708 يتولى المحللون فقط التعليقات البنية بدءًا من سمة @Description . لكنه يكتب جميع التعليقات الحقل الهيكلي كما هي.
لذلك ، مستند Swagger الذي تم إنشاؤه على النحو التالي:
"Account" : {
"type" : " object " ,
"description" : " User account information with user id and username "
"properties" : {
"id" : {
"type" : " integer " ,
"description" : " ID this is userid "
},
"name" : {
"type" : " string " ,
"description" : " This is Name "
}
}
}#201
type TimestampTime struct {
time. Time
}
///implement encoding.JSON.Marshaler interface
func ( t * TimestampTime ) MarshalJSON () ([] byte , error ) {
bin := make ([] byte , 16 )
bin = strconv . AppendInt ( bin [: 0 ], t . Time . Unix (), 10 )
return bin , nil
}
func ( t * TimestampTime ) UnmarshalJSON ( bin [] byte ) error {
v , err := strconv . ParseInt ( string ( bin ), 10 , 64 )
if err != nil {
return err
}
t . Time = time . Unix ( v , 0 )
return nil
}
///
type Account struct {
// Override primitive type by simply specifying it via `swaggertype` tag
ID sql. NullInt64 `json:"id" swaggertype:"integer"`
// Override struct type to a primitive type 'integer' by specifying it via `swaggertype` tag
RegisterTime TimestampTime `json:"register_time" swaggertype:"primitive,integer"`
// Array types can be overridden using "array,<prim_type>" format
Coeffs []big. Float `json:"coeffs" swaggertype:"array,number"`
}#379
type CerticateKeyPair struct {
Crt [] byte `json:"crt" swaggertype:"string" format:"base64" example:"U3dhZ2dlciByb2Nrcw=="`
Key [] byte `json:"key" swaggertype:"string" format:"base64" example:"U3dhZ2dlciByb2Nrcw=="`
}مستند Swagger الذي تم إنشاؤه على النحو التالي:
"api.MyBinding" : {
"type" :" object ",
"properties" :{
"crt" :{
"type" :" string ",
"format" :" base64 ",
"example" :" U3dhZ2dlciByb2Nrcw == "
},
"key" :{
"type" :" string ",
"format" :" base64 ",
"example" :" U3dhZ2dlciByb2Nrcw == "
}
}
} إذا كنت تستخدم ملفات تم إنشاؤها ، فقد لا تكون علامات swaggertype أو swaggerignore ممكنة.
من خلال تمرير رسم الخرائط إلى غنيمة --overridesFile يمكنك إخبار Swag باستخدام نوع واحد في مكان آخر أينما ظهر. افتراضيًا ، إذا كان ملف .swaggo موجودًا في الدليل الحالي ، فسيتم استخدامه.
GO CODE:
type MyStruct struct {
ID sql. NullInt64 `json:"id"`
Name sql. NullString `json:"name"`
} .swaggo :
// Replace all NullInt64 with int
replace database/sql.NullInt64 int
// Don't include any fields of type database/sql.NullString in the swagger docs
skip database/sql.NullString
التوجيهات الممكنة هي التعليقات (بدءًا من // ) ، replace path/to/a.type path/to/b.type ، skip path/to/a.type .
(لاحظ أنه يجب توفير المسارات الكاملة لأي أنواع تسمية لمنع المشكلات عندما تحدد حزم متعددة نوعًا بنفس الاسم)
المقدمة:
"types.MyStruct" : {
"id" : "integer"
} type Account struct {
ID string `json:"id"`
Name string `json:"name"`
Ignored int `swaggerignore:"true"`
} type Account struct {
ID string `json:"id" extensions:"x-nullable,x-abc=def,!x-omitempty"` // extensions fields must start with "x-"
}توليد مستند Swagger على النحو التالي:
"Account" : {
"type" : "object" ,
"properties" : {
"id" : {
"type" : "string" ,
"x-nullable" : true ,
"x-abc" : "def" ,
"x-omitempty" : false
}
}
} type Resp struct {
Code int
} //@name Responseمعلومات API العامة.
// @securityDefinitions.basic BasicAuth
// @securitydefinitions.oauth2.application OAuth2Application
// @tokenUrl https://example.com/oauth/token
// @scope.write Grants write access
// @scope.admin Grants read and write access to administrative informationكل عملية API.
// @Security ApiKeyAuthاجعله أو حالة
// @Security ApiKeyAuth
// @Security OAuth2Application[write, admin]اصنعها وحالة
// @Security ApiKeyAuth && firebase
// @Security OAuth2Application[write, admin] && APIKeyAuth type Example struct {
// Sort order:
// * asc - Ascending, from A to Z.
// * desc - Descending, from Z to A.
Order string `enums:"asc,desc"`
} بشكل افتراضي ، يقوم الأمر swag بإنشاء مواصفات Swagger في ثلاثة أنواع مختلفة من الملفات/الملفات:
إذا كنت ترغب في الحد من مجموعة من أنواع الملفات التي يجب إنشاؤها ، فيمكنك استخدام --outputTypes (قصيرة -ot ). القيمة الافتراضية هي go,json,yaml - أنواع الإخراج مفصولة مع الفاصلة. للحد من الإخراج فقط go وملفات yaml ، يمكنك الكتابة go,yaml . مع الأمر الكامل الذي سيكون swag init --outputTypes go,yaml .
// @Success 200 {object} web.GenericNestedResponse[types.Post]
// @Success 204 {object} web.GenericNestedResponse[types.Post, Types.AnotherOne]
// @Success 201 {object} web.GenericNestedResponse[web.GenericInnerType[types.Post]]
func GetPosts ( w http. ResponseWriter , r * http. Request ) {
_ = web. GenericNestedResponse [types. Post ]{}
}انظر هذا الملف لمزيد من التفاصيل والأمثلة الأخرى.
#980 #1177
إذا كانت التعليقات التوضيحية أو الحقول البنية الخاصة بك تحتوي على "{{" أو "}}" ، فمن المرجح أن يفشل توليد القالب ، لأن هذه هي المحددات الافتراضية لقوالب GO.
لجعل الجيل يعمل بشكل صحيح ، يمكنك تغيير المحددات الافتراضية مع -td . على سبيل المثال:
swag init -g http/api.go -td "[[,]]" المحدد الجديد عبارة عن سلسلة بتنسيق " <left delimiter> ، <right delimiter> ".
إذا تم تعريف البنية في حزمة التبعية ، فاستخدم --parseDependency .
إذا تم تعريف البنية في مشروعك الرئيسي ، فاستخدم --parseInternal .
إذا كنت ترغب في تضمين كلاهما الداخلي ومن التبعيات ، فاستخدم كلتا العلامات
swag init --parseDependency --parseInternal
استلهم هذا المشروع من Yvasiyarov/Swagger لكننا قمنا بتبسيط الاستخدام وأضفنا دعمًا مجموعة متنوعة من أطر عمل الويب. مصدر صورة Gopher هو Tenntenn/Gopher-Stickers. لديها تراخيص ترخيص المشاع الإبداعي.
هذا المشروع موجود بفضل جميع الأشخاص الذين يساهمون. [يساهم].
شكرا لجميع مؤيدينا! [كن مؤيدًا]
دعم هذا المشروع من خلال أن يصبح راعياً. سيظهر شعارك هنا مع رابط لموقع الويب الخاص بك. [كن راعياً]
