کتابخانه‌ی استاندارد · شبکه

سواگر `net/http/swagger`

نوشتن مستندات OpenAPI برای API و نمایش صفحه‌ی مستندات.

واردسازی شبکه.اچ تی تی پی.سواگر

در این صفحه

مستند کردن API کنار مسیرهایش
طرح‌های احراز هویت و ذخیره‌ی مشخصات
بررسی مستندات در CI
سرو مستندات همراه API
گونه‌ها
پایاها و متغیرها
تابع‌ها

این بسته مستندات یک API از نوع HTTP را به شکل سند OpenAPI 3.1 می‌نویسد و آن را با صفحه‌ای سرو می‌کند که در آن هر عملیات خوانده و آزموده می‌شود. آن را کنار APIای که با اچ تی تی پی و مسیریاب ساخته‌اید به کار ببرید: سازنده‌های کارخواه، دروازه‌های API و تیم فرانت‌اند همه همان openapi.json را می‌خوانند. صفحه‌ی نمایش درون خود بسته است، پس بدون اینترنت کار می‌کند و چیزی از CDN بار نمی‌کند.

اجزا چطور کنار هم قرار می‌گیرند:

یک سند کل مستندات را نگه می‌دارد. مسیر عملیاتی می‌افزاید (یا انتخاب مسیر عملیات موجودی را برمی‌گزیند) و فراخوانی‌های بعدی، مثل خلاصه، پرسمان و برمی گرداند، همان عملیات را توصیف می‌کنند.
طرحواره‌ی بدنه و پاسخ از یک مقدار نمونه ساخته می‌شود: یک ساختار خالی بدهید تا فیلدهایش، با نام‌های @جیسون، طرحواره‌ای زیر components شوند.
نصب صفحه‌ی نمایش و مشخصات را به مسیریاب شما می‌افزاید؛ مشکلات، جا افتاده و توضیح داده نشده سند را در آزمون بررسی می‌کنند.

چیزهایی که بیشتر غافلگیر می‌کنند:

نصب همان لحظه از مشخصات رونوشت می‌گیرد و مسیرهایی به مسیریاب می‌افزاید. اول همه‌ی مسیرها را توصیف کنید، سپس نصب و بعد اچ تی تی پی.استفاده؛ توضیحی که پس از نصب اضافه شود هرگز به صفحه نمی‌رسد.
پس از انتخاب مسیری که چیزی پیدا نکند، فراخوانی‌های بعدی کاری نمی‌کنند. خروجی انتخاب مسیر را بسنجید یا مسیر را به کار ببرید که عملیات را می‌سازد.
مستندات عمومی است. هر کسی که به سرور برسد /docs را می‌خواند و مشخصات با Access-Control-Allow-Origin: * سرو می‌شود. اگر API خصوصی است، نصب را در نسخه‌ی تولید نگذارید.

مستند کردن API کنار مسیرهایش

ساده‌ترین عادت این است که هر مسیر را درست پس از ثبتش توصیف کنید تا این دو هیچ‌وقت از هم جدا نشوند. مسیر یک عملیات را آغاز می‌کند و تابع‌های بعدی آن را کامل می‌کنند. برمی گرداند یک مقدار نمونه می‌گیرد: یک ساختار بدهید، یا برای فهرست آرایه‌ای از یک ساختار، تا طرحواره زیر components بیاید. سپس نصب مشخصات را در /docs/openapi.json و صفحه‌ی نمایش را در /docs سرو می‌کند.

net-http-swagger-api.salam

واردسازی شبکه.اچ تی تی پی
واردسازی شبکه.اچ تی تی پی.سواگر
واردسازی شبکه.مسیریاب
واردسازی کدگذاری.جیسون

ساختار کار:
    @جیسون "id"
    همگانی شناسه: صحیح = ۰
    @جیسون "title"
    همگانی عنوان: رشته = ""
    @جیسون "done"
    همگانی انجام شده: منطقی = نادرست
پایان

تابع فهرست(ز: صحیح۶۴):
    اچ تی تی پی.جیسون(ز، `[{"id":1,"title":"نوشتن مستندات","done":false}]`)
پایان

تابع ساختن(ز: صحیح۶۴):
    اچ تی تی پی.تنظیم وضعیت(ز، ۲۰۱)
    اچ تی تی پی.جیسون(ز، اچ تی تی پی.بدنه(ز))
پایان

تابع ریشه:
    ناپایا م := مسیریاب.مسیریاب جدید()
    ناپایا سند := سواگر.جدید("tasks"، "1.0.0")
    مسیریاب.دریافت(م، "/tasks"، فهرست)
    _ := سواگر.مسیر(سند، "GET"، "/tasks")
    سواگر.خلاصه(سند، "همه‌ی کارها")
    سواگر.برچسب(سند، "tasks")
    سواگر.برمی گرداند(سند، ۲۰۰، "کارها"، [کار {}])
    مسیریاب.ارسال(م، "/tasks"، ساختن)
    _ := سواگر.مسیر(سند، "POST"، "/tasks")
    سواگر.خلاصه(سند، "افزودن یک کار")
    سواگر.برچسب(سند، "tasks")
    سواگر.می پذیرد(سند، "کار تازه"، کار {})
    سواگر.برمی گرداند(سند، ۲۰۱، "کار ذخیره شده"، کار {})
    سرچاپ "جا افتاده:"، سواگر.جا افتاده(سند، م)
    سواگر.نصب(سند، م، "/docs")
    ناپایا س := اچ تی تی پی.سرور جدید(۱۹۷۹۴)
    اچ تی تی پی.استفاده(س، م)
    _ := اچ تی تی پی.اجرا در پس زمینه(س)
    مشخصات := اچ تی تی پی.بدنه(اچ تی تی پی.دریافت("http://127.0.0.1:19794/docs/openapi.json"))
    سرچاپ جیسون.کلیدها(جیسون.دریافت(مشخصات، "paths"))
    سرچاپ جیسون.دریافت مسیر(مشخصات، "paths./tasks.post.summary")
    سرچاپ جیسون.دریافت مسیر(مشخصات، "paths./tasks.get.responses.200.description")
    سرچاپ جیسون.دریافت مسیر(مشخصات، "paths./tasks.get.responses.200.content")
    سرچاپ جیسون.کلیدها(جیسون.دریافت مسیر(مشخصات، "components.schemas.کار.properties"))
    سرچاپ اچ تی تی پی.وضعیت(اچ تی تی پی.دریافت("http://127.0.0.1:19794/docs"))
    سواگر.آزاد سازی(سند)
پایان

خروجیجا افتاده: [] ["/tasks"] افزودن یک کار کارها {"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/کار"}}}} ["id", "title", "done"] 200

نصب هنگام صدا زدن از مشخصات رونوشت می‌گیرد، پس اول همه‌ی مسیرها را مستند کنید و در آخر نصب کنید. الگوی مسیرها به شکل مسیریاب نوشته می‌شود، /books/:id، و به شکل OpenAPI درمی‌آید، /books/{id}. نام ساختار هم نام طرحواره می‌شود، برای همین اینجا طرحواره کار نام دارد.

طرح‌های احراز هویت و ذخیره‌ی مشخصات

هر روش ورود را یک بار تعریف کنید: احراز هویت حامل برای توکن در سرآیند Authorization، یا احراز هویت کلید برای کلیدی در سرآیند، پرسمان یا کوکی. سپس هر عملیاتی را که به آن نیاز دارد با امن و نام طرح علامت بزنید. نوشتن مشخصات مشخصات را در پرونده ذخیره می‌کند، برای سازنده‌ی کارخواه یا انتشار همراه سایت، و مشخصات از پرونده آن را دوباره می‌خواند.

net-http-swagger-auth.salam

واردسازی شبکه.اچ تی تی پی.سواگر
واردسازی کدگذاری.جیسون

ساختار فاکتور:
    @جیسون "number"
    همگانی شماره: رشته = ""
    @جیسون "total"
    همگانی جمع: اعشار۶۴ = ۰.۰
پایان

تابع ریشه:
    ناپایا سند := سواگر.جدید("billing"، "1.4.0")
    سواگر.سرور(سند، "https://billing.example.com"، "اصلی")
    سواگر.احراز هویت حامل(سند، "user"، "JWT")
    سواگر.احراز هویت کلید(سند، "partner"، "header"، "X-Partner-Key")
    _ := سواگر.مسیر(سند، "GET"، "/invoices/:number")
    سواگر.خلاصه(سند، "یک فاکتور")
    سواگر.امن(سند، "user")
    سواگر.برمی گرداند(سند، ۲۰۰، "فاکتور"، فاکتور {})
    سواگر.بدون بدنه برمی گرداند(سند، ۴۰۱، "توکن معتبر نیست")
    _ := سواگر.مسیر(سند، "POST"، "/partner/invoices")
    سواگر.خلاصه(سند، "شریک تجاری فاکتور می‌فرستد")
    سواگر.امن(سند، "partner")
    سواگر.می پذیرد(سند، "فاکتور"، فاکتور {})
    سواگر.بدون بدنه برمی گرداند(سند، ۲۰۲، "پذیرفته شد")
    سرچاپ "مشکلات:"، سواگر.مشکلات(سند).طول()
    سرچاپ سواگر.نوشتن مشخصات(سند، "openapi.json")
    مشخصات := سواگر.مشخصات از پرونده("openapi.json")
    سرچاپ جیسون.فشرده سازی(جیسون.دریافت مسیر(مشخصات، "components.securitySchemes.user"))
    سرچاپ جیسون.فشرده سازی(جیسون.دریافت مسیر(مشخصات، "components.securitySchemes.partner"))
    سرچاپ جیسون.فشرده سازی(جیسون.دریافت مسیر(مشخصات، "paths./invoices/{number}.get.security"))
    سرچاپ جیسون.دریافت مسیر(مشخصات، "components.schemas.فاکتور.properties.total.type")
    سواگر.آزاد سازی(سند)
پایان

خروجیمشکلات: 0 true {"type":"http","scheme":"bearer","bearerFormat":"JWT"} {"type":"apiKey","in":"header","name":"X-Partner-Key"} [{"user":[]}] number

بررسی مستندات در CI

مستندات بی‌صدا کهنه می‌شوند. مشکلات اشتباه‌های خود مشخصات را پیدا می‌کند: طرح احراز هویتی که هرگز تعریف نشده، پارامتر مسیری که با مسیر جور نیست، کد وضعیتی بیرون از ۱۰۰ تا ۵۹۹، بدنه روی GET، یا شناسه‌ی عملیات تکراری. جا افتاده مشخصات را با مسیریاب مقایسه می‌کند و مسیرهایی را که عملیات ندارند فهرست می‌کند. هر دو را در یک آزمون چاپ کنید و اگر هیچ‌کدام خالی نبود، ساخت را شکست دهید.

net-http-swagger-check.salam

واردسازی شبکه.اچ تی تی پی
واردسازی شبکه.اچ تی تی پی.سواگر
واردسازی شبکه.مسیریاب

تابع هیچ(ز: صحیح۶۴):
    اچ تی تی پی.متن(ز، "")
پایان

تابع ریشه:
    ناپایا م := مسیریاب.مسیریاب جدید()
    مسیریاب.دریافت(م، "/users/:id"، هیچ)
    مسیریاب.حذف(م، "/users/:id"، هیچ)
    مسیریاب.دریافت(م، "/reports"، هیچ)
    ناپایا سند := سواگر.جدید("users"، "2.0.0")
    _ := سواگر.مسیر(سند، "GET"، "/users/:id")
    سواگر.خلاصه(سند، "یک کاربر")
    سواگر.امن(سند، "token")
    سواگر.برمی گرداند متن(سند، ۲۰۰، "کاربر")
    _ := سواگر.مسیر(سند، "DELETE"، "/users/:id")
    سواگر.پارامتر مسیر(سند، "id"، "شناسه‌ی کاربر")
    سواگر.بدون بدنه برمی گرداند(سند، ۲۰۴۰، "حذف شد")
    ناپایا شمار := ۰
    هر مشکل در سواگر.مشکلات(سند):
        سرچاپ "مشکل:"، مشکل
        شمار += ۱
    پایان
    هر مسیر در سواگر.جا افتاده(سند، م):
        سرچاپ "مستند نشده:"، مسیر
        شمار += ۱
    پایان
    سرچاپ شمار، "مورد،"، شمار > ۰ ? "پس ساخت شکست می‌خورد" : "پس ساخت می‌گذرد"
    سواگر.آزاد سازی(سند)
پایان

خروجیمشکل: GET /users/:id: needs security scheme 'token', which no BearerAuth or ApiKeyAuth declared مشکل: DELETE /users/:id: 2040 is not an HTTP status code مستند نشده: GET /reports 3 مورد، پس ساخت شکست می‌خورد

در بررسی واقعی، وقتی شمار بیش از صفر است از ریشه عدد ۱ را برگردانید تا کار CI شکست بخورد. توضیح داده نشده بررسی نرم‌تری است: عملیات‌هایی را فهرست می‌کند که هستند ولی نه خلاصه دارند، نه توضیح و نه پاسخ.

سرو مستندات همراه API

برای مسیریابی که از قبل دارید، پویش برای هر مسیر یک عملیات خالی می‌سازد تا هیچ مسیری از قلم نیفتد. سپس انتخاب مسیر یکی از آن‌ها را برای توصیف انتخاب می‌کند. می پذیرد خام و برمی گرداند خام یک نوع محتوا و یک طرحواره‌ی JSON Schema به صورت متن می‌گیرند، برای بدنه‌هایی که ساختار نیستند.

net-http-swagger-serve.salam

واردسازی شبکه.اچ تی تی پی
واردسازی شبکه.اچ تی تی پی.سواگر
واردسازی شبکه.مسیریاب

تابع پینگ(ز: صحیح۶۴):
    اچ تی تی پی.متن(ز، "pong")
پایان

تابع پژواک(ز: صحیح۶۴):
    اچ تی تی پی.جیسون(ز، اچ تی تی پی.بدنه(ز))
پایان

تابع ریشه:
    ناپایا م := مسیریاب.مسیریاب جدید()
    مسیریاب.دریافت(م، "/ping"، پینگ)
    مسیریاب.ارسال(م، "/echo"، پژواک)
    ناپایا سند := سواگر.جدید("echo service"، "0.1.0")
    سواگر.توضیح(سند، "به پینگ پاسخ می‌دهد و جیسون را همان‌طور که آمده برمی‌گرداند.")
    سواگر.سرور(سند، "http://localhost:8080"، "همین دستگاه")
    سواگر.پویش(سند، م)
    _ := سواگر.انتخاب مسیر(سند، "GET"، "/ping")
    سواگر.خلاصه(سند، "آیا سرویس بالا است")
    سواگر.برمی گرداند متن(سند، ۲۰۰، "همیشه pong")
    _ := سواگر.انتخاب مسیر(سند، "POST"، "/echo")
    سواگر.خلاصه(سند، "جیسون بفرستید و همان را پس بگیرید")
    سواگر.می پذیرد خام(سند، "هر مقدار جیسون"، سواگر.نوع جیسون، "{}"، درست)
    سواگر.برمی گرداند خام(سند، ۲۰۰، "همان مقدار"، سواگر.نوع جیسون، "{}")
    سواگر.نصب(سند، م، "/docs")
    ناپایا س := اچ تی تی پی.سرور جدید(۸۰۸۰)
    اچ تی تی پی.استفاده(س، م)
    سرچاپ "مستندات در http://localhost:8080/docs"
    اچ تی تی پی.اجرا(س)
پایان

آن را با salam run اجرا کنید و http://localhost:8080/docs را در مرورگر باز کنید: صفحه هر دو عملیات را نشان می‌دهد و جعبه‌ی Try it زیر هر کدام درخواست واقعی به سرور در حال اجرا می‌فرستد. اگر اصلاً مسیریاب ندارید، سرو یک سرور کوچک فقط برای مستندات راه می‌اندازد و سرو مشخصات همین کار را برای مشخصاتی که دستی نوشته شده می‌کند.

گونه‌ها

پارامتر `Param`

ساختار پارامتر

یک پارامتر.

نام	انگلیسی	گونه	توضیح
نام	`name`	`رشته = ""`	نام.
جا	`loc`	`رشته = "query"`	جا: query، header، cookie یا path.
الزامی	`required`	`منطقی = نادرست`	الزامی.
توضیح	`description`	`رشته = ""`	توضیح.
طرحواره	`schema`	`رشته = "{"گونه":"string"}"`	طرحواره.

net-http-swagger-Build.salam

واردسازی شبکه.اچ تی تی پی.سواگر
واردسازی کدگذاری.جیسون

ساختار کتاب:
    @جیسون "id"
    همگانی شناسه: صحیح = ۰
    @جیسون "title"
    همگانی عنوان: رشته = ""
پایان

تابع ریشه:
    ناپایا س := سواگر.جدید("کتابخانه"، "1.2.0")
    سواگر.توضیح(س، "API نمونه برای کتاب‌ها")
    سواگر.سرور(س، "https://api.example.com"، "اصلی")
    سواگر.تماس(س، "تیم سلام"، "https://salamlang.ir"، "[email protected]")
    سواگر.پروانه(س، "MIT"، "https://opensource.org/licenses/MIT")
    سواگر.احراز هویت حامل(س، "token"، "JWT")
    سواگر.احراز هویت کلید(س، "key"، "header"، "X-API-Key")
    _ := سواگر.مسیر(س، "GET"، "/books/:id")
    سواگر.خلاصه(س، "یک کتاب")
    سواگر.جزئیات(س، "کتاب را با شناسه برمی‌گرداند.")
    سواگر.برچسب(س، "books")
    سواگر.شناسه عملیات(س، "getBook")
    سواگر.پارامتر مسیر(س، "id"، "شناسه‌ی کتاب")
    سواگر.پرسمان(س، "fields"، "فیلدهای خواسته‌شده"، نادرست)
    سواگر.پرسمان نوع دار(س، "limit"، "حداکثر"، نادرست، ۱۰)
    ناپایا ترتیب‌ها := وکتور {} برگردان وکتور<رشته>
    ترتیب‌ها.بیفزا("title")
    ترتیب‌ها.بیفزا("id")
    سواگر.پرسمان گزینه ای(س، "sort"، "ترتیب"، نادرست، ترتیب‌ها)
    سواگر.سرصفحه(س، "X-Trace"، "شناسه‌ی رهگیری"، نادرست)
    سواگر.کوکی(س، "sid"، "نشست"، نادرست)
    سواگر.امن(س، "token")
    سواگر.برمی گرداند(س، ۲۰۰، "کتاب"، کتاب {})
    سواگر.برمی گرداند سرصفحه(س، ۲۰۰، "ETag"، "نسخه")
    سواگر.بدون بدنه برمی گرداند(س، ۴۰۴، "پیدا نشد")
    _ := سواگر.مسیر(س، "POST"، "/books")
    سواگر.می پذیرد(س، "کتاب تازه"، کتاب {})
    سواگر.برمی گرداند(س، ۲۰۱، "ساخته شد"، کتاب {})
    _ := سواگر.مسیر(س، "PUT"، "/books/:id/cover")
    سواگر.می پذیرد خام(س، "تصویر جلد"، "image/png"، "{\"type\":\"string\",\"format\":\"binary\"}"، درست)
    سواگر.برمی گرداند متن(س، ۲۰۰، "انجام شد")
    _ := سواگر.مسیر(س، "POST"، "/books/:id/notes")
    سواگر.می پذیرد اختیاری(س، "یادداشت"، کتاب {})
    سواگر.می پذیرد فرم(س، "فرم"، کتاب {})
    سواگر.برمی گرداند خام(س، ۲۰۰، "خروجی"، "text/csv"، "{\"type\":\"string\"}")
    سواگر.برمی گرداند اچ تی ام ال(س، ۲۰۰، "صفحه")
    سواگر.برمی گرداند پرونده(س، ۲۰۰، "پرونده"، "application/pdf")
    سواگر.منسوخ(س)
    سرچاپ سواگر.انتخاب مسیر(س، "get"، "/books/:id")، سواگر.انتخاب مسیر(س، "GET"، "/nope")
    سرچاپ س.عملیات‌ها.طول()، س.عملیات‌ها[۰].پارامترها.طول()، س.عملیات‌ها[۰].پاسخ‌ها.طول()، س.عملیات‌ها[۳].منسوخ، س.روش‌های احراز هویت.طول()
    متن := سواگر.مشخصات(س)
    سرچاپ جیسون.معتبر(متن)، جیسون.دریافت(متن، "openapi")
    سرچاپ سواگر.مشخصات با تورفتگی(س).طول() > متن.طول()
    سرچاپ سواگر.مشکلات(س).طول()، سواگر.توضیح داده نشده(س)
    سرچاپ سواگر.نوشتن مشخصات(س، "openapi.json")، سواگر.مشخصات از پرونده("openapi.json").طول() > ۰، سواگر.مشخصات از پرونده("نیست.json")
    سرچاپ سواگر.طرحواره متن، سواگر.نوع جیسون
    سواگر.آزاد سازی(س)
پایان

خروجیtrue false 4 6 2 true 2 true 3.1.0 true 0 [] true true {"type":"string"} application/json

پاسخ `Reply`

ساختار پاسخ

یک پاسخ.

نام	انگلیسی	گونه	توضیح
کد	`code`	`صحیح = 200`	کد وضعیت.
توضیح	`description`	`رشته = ""`	توضیح.
طرحواره	`schema`	`رشته = ""`	طرحواره‌ی بدنه.
نوع محتوا	`content_type`	`رشته = "application/json"`	نوع محتوا.
نام سرآیندها	`header_names`	`وکتور<رشته>`	نام سرآیندهای پاسخ.
توضیح سرآیندها	`header_notes`	`وکتور<رشته>`	توضیح آن‌ها.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

طرح احراز هویت `Scheme`

ساختار طرح احراز هویت

یک روش احراز هویت.

نام	انگلیسی	گونه	توضیح
نام	`name`	`رشته = ""`	نام.
نوع	`kind`	`رشته = "http"`	نوع: http یا apiKey.
طرح	`scheme`	`رشته = "bearer"`	برای http، مثل bearer.
قالب	`format`	`رشته = ""`	قالب توکن، مثل JWT.
جا	`loc`	`رشته = "header"`	جای کلید.
پارامتر کلید	`param`	`رشته = ""`	نام پارامتر کلید.
توضیح	`description`	`رشته = ""`	توضیح.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

عملیات `Op`

ساختار عملیات

یک عملیات: یک روش روی یک مسیر.

نام	انگلیسی	گونه	توضیح
روش	`method`	`رشته = ""`	روش.
الگوی مسیر	`pattern`	`رشته = ""`	الگوی مسیر.
شناسه عملیات	`op_id`	`رشته = ""`	شناسه‌ی عملیات.
خلاصه	`summary`	`رشته = ""`	خلاصه.
توضیح	`description`	`رشته = ""`	توضیح.
منسوخ	`is_deprecated`	`منطقی = نادرست`	منسوخ است.
برچسب‌ها	`tags`	`وکتور<رشته>`	برچسب‌ها.
پارامترها	`params`	`وکتور<پارامتر>`	پارامترها.
پاسخ‌ها	`replies`	`وکتور<پاسخ>`	پاسخ‌ها.
روش‌های احراز هویت	`security`	`وکتور<رشته>`	روش‌های احراز هویت لازم.
طرحواره بدنه	`body_schema`	`رشته = ""`	طرحواره‌ی بدنه.
توضیح بدنه	`body_description`	`رشته = ""`	توضیح بدنه.
بدنه الزامی	`body_required`	`منطقی = درست`	بدنه الزامی است.
نوع محتوای بدنه	`body_content_type`	`رشته = "application/json"`	نوع محتوای بدنه.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

تعریف `Definition`

ساختار تعریف

تعریف یک گونه در طرحواره.

نام	انگلیسی	گونه	توضیح
نام	`name`	`رشته = ""`	نام.
طرحواره	`body`	`رشته = ""`	طرحواره‌ی جیسون.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

سند `Doc`

ساختار سند

سند OpenAPI در حال ساخت.

نام	انگلیسی	گونه	توضیح
عنوان	`title`	`رشته = "API"`	عنوان API.
نسخه	`version`	`رشته = "1.0.0"`	نسخه.
توضیح	`description`	`رشته = ""`	توضیح.
سرورها	`servers`	`وکتور<رشته>`	نشانی سرورها.
توضیح سرورها	`server_notes`	`وکتور<رشته>`	توضیح هر سرور.
عملیات‌ها	`ops`	`وکتور<عملیات>`	عملیات‌ها.
تعریف‌ها	`defs`	`وکتور<تعریف>`	تعریف گونه‌ها.
روش‌های احراز هویت	`schemes`	`وکتور<طرح احراز هویت>`	روش‌های احراز هویت.
نام تماس	`contact_name`	`رشته = ""`	نام تماس.
نشانی تماس	`contact_url`	`رشته = ""`	نشانی تماس.
ایمیل تماس	`contact_email`	`رشته = ""`	ایمیل تماس.
نام پروانه	`license_name`	`رشته = ""`	نام پروانه.
نشانی پروانه	`license_url`	`رشته = ""`	نشانی پروانه.
عملیات فعلی	`cur`	`صحیح = -1`	شماره‌ی عملیات فعلی؛ تابع‌های توصیف روی همین کار می‌کنند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

پایاها و متغیرها

نوع جیسون `JSON_TYPE`

پایا نوع جیسون: رشته = "application/json"

نوع محتوای جیسون.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

نوع متن `TEXT_TYPE`

پایا نوع متن: رشته = "text/plain; charset=utf-8"

نوع محتوای متن ساده.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

نوع اچ تی ام ال `HTML_TYPE`

پایا نوع اچ تی ام ال: رشته = "text/html; charset=utf-8"

نوع محتوای HTML.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

نوع فرم `FORM_TYPE`

پایا نوع فرم: رشته = "application/x-www-form-urlencoded"

نوع محتوای فرم.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

طرحواره متن `TEXT_SCHEMA`

پایا طرحواره متن: رشته = "{"گونه":"string"}"

طرحواره‌ی رشته.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

طرحواره دودویی `BINARY_SCHEMA`

پایا طرحواره دودویی: رشته = "{"گونه":"string"،"format":"binary"}"

طرحواره‌ی داده‌ی دودویی، برای پرونده‌ها.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

تابع‌ها

پویش `Scan`

تابع پویش(d &: سند، r: router.Router)

برای همه‌ی مسیرهای مسیریاب عملیات می‌سازد تا بعد توصیفشان کنید.

net-http-swagger-Serve.salam

واردسازی شبکه.اچ تی تی پی
واردسازی شبکه.اچ تی تی پی.سواگر
واردسازی شبکه.مسیریاب
واردسازی رشته

تابع فهرست(ز: صحیح۶۴):
    اچ تی تی پی.جیسون(ز، "[]")
پایان

تابع ریشه:
    ناپایا م := مسیریاب.مسیریاب جدید()
    مسیریاب.دریافت(م، "/books"، فهرست)
    مسیریاب.ارسال(م، "/books"، فهرست)
    مسیریاب.دریافت(م، "/admin/stats"، فهرست)
    ناپایا س := سواگر.جدید("کتابخانه"، "1.0.0")
    سرچاپ سواگر.جا افتاده(س، م)
    سواگر.پویش با پیشوند(س، م، "/books")
    سرچاپ س.عملیات‌ها.طول()، سواگر.جا افتاده(س، م)
    سواگر.پویش(س، م)
    سرچاپ س.عملیات‌ها.طول()، سواگر.جا افتاده(س، م).طول()
    سواگر.نصب(س، م، "/docs")
    ناپایا سرور := اچ تی تی پی.سرور جدید(۱۹۶۰۷)
    اچ تی تی پی.استفاده(سرور، م)
    _ := اچ تی تی پی.اجرا در پس زمینه(سرور)
    پ := اچ تی تی پی.دریافت("http://127.0.0.1:19607/docs/openapi.json")
    سرچاپ اچ تی تی پی.وضعیت(پ)، رشته.شامل است(اچ تی تی پی.بدنه(پ)، "/admin/stats")
    صفحه := اچ تی تی پی.دریافت("http://127.0.0.1:19607/docs")
    سرچاپ رشته.شامل است(اچ تی تی پی.بدنه(صفحه)، "<html")
    ناپایا م۲ := مسیریاب.مسیریاب جدید()
    سواگر.نصب مشخصات("{\"openapi\":\"3.1.0\"}"، "آماده"، م۲، "/spec")
    سرچاپ م۲.مسیرها.طول()
    سرچاپ سواگر.سرو(س، ۱۹۶۰۸)، اچ تی تی پی.وضعیت(اچ تی تی پی.دریافت("http://127.0.0.1:19608/openapi.json"))
    سرچاپ سواگر.سرو مشخصات("{\"openapi\":\"3.1.0\"}"، "دیگر"، ۱۹۶۰۹)
    سرچاپ رشته.شامل است(سواگر.صفحه("API"، "/openapi.json")، "/openapi.json")
پایان

خروجی["GET /books", "POST /books", "GET /admin/stats"] 2 ["GET /admin/stats"] 3 0 200 true true 3 true 200 true true

پویش با پیشوند `ScanPrefix`

تابع پویش با پیشوند(d &: سند، r: router.Router، prefix: رشته)

مثل تابع بالا، فقط برای مسیرهای با این پیشوند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Serve.salam

صفحه `Page`

تابع صفحه(title: رشته، spec_url: رشته): رشته

متن HTML صفحه‌ی مستندات که مشخصات را از نشانی داده‌شده می‌خواند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Serve.salam

مشخصات `Spec`

تابع مشخصات(d: سند): رشته

سند را به جیسون OpenAPI 3.1 تبدیل می‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

مشخصات با تورفتگی `SpecIndent`

تابع مشخصات با تورفتگی(d: سند): رشته

مثل تابع بالا، خوانا با تورفتگی.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

نصب `Mount`

تابع نصب(d: سند، r &: router.Router، prefix: رشته)

صفحه‌ی مستندات و openapi.json را، با مشخصات همان لحظه، زیر پیشوند داده‌شده به مسیریاب اضافه می‌کند. پیش از اچ تی تی پی.استفاده صدایش بزنید.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Serve.salam

نصب مشخصات `MountSpec`

تابع نصب مشخصات(spec: رشته، title: رشته، r &: router.Router، prefix: رشته)

مثل تابع بالا، با مشخصات آماده.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Serve.salam

سرو `Serve`

تابع سرو(d: سند، port: صحیح): منطقی

صفحه‌ی مستندات را روی درگاه جدا در پس‌زمینه اجرا می‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Serve.salam

سرو مشخصات `ServeSpec`

تابع سرو مشخصات(spec: رشته، title: رشته، port: صحیح): منطقی

مثل تابع بالا، با مشخصات آماده.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Serve.salam

مشخصات از پرونده `SpecFromFile`

تابع مشخصات از پرونده(path: رشته): رشته

مشخصات آماده را از پرونده می‌خواند؛ اگر نباشد، رشته‌ی خالی.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

نوشتن مشخصات `WriteSpec`

تابع نوشتن مشخصات(d: سند، path: رشته): منطقی

سند را در پرونده می‌نویسد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

مشکلات `Problems`

تابع مشکلات(d: سند): وکتور<رشته>

ایرادهای سند: عنوان یا نسخه‌ی خالی، شناسه‌ی تکراری و مانند آن.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

توضیح داده نشده `Undocumented`

تابع توضیح داده نشده(d: سند): وکتور<رشته>

عملیات‌هایی که خلاصه، توضیح و پاسخ ندارند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

جا افتاده `Missing`

تابع جا افتاده(d: سند، r: router.Router): وکتور<رشته>

مسیرهایی از مسیریاب که در سند نیستند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Serve.salam

آزاد سازی `Free`

تابع آزاد سازی(d &: سند)

حافظه‌ی سند را آزاد می‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

جدید `New`

تابع جدید(title: رشته، version: رشته): سند

سند تازه با عنوان و نسخه.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

توضیح `Describe`

تابع توضیح(d &: سند، text: رشته)

توضیح کلی API.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

سرور `Server`

تابع سرور(d &: سند، url: رشته، note: رشته)

نشانی یک سرور را با توضیح اضافه می‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

تماس `Contact`

تابع تماس(d &: سند، name: رشته، url: رشته، email: رشته)

اطلاعات تماس.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

پروانه `License`

تابع پروانه(d &: سند، name: رشته، url: رشته)

پروانه.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

احراز هویت حامل `BearerAuth`

تابع احراز هویت حامل(d &: سند، name: رشته، format: رشته)

احراز هویت با توکن Bearer تعریف می‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

احراز هویت کلید `ApiKeyAuth`

تابع احراز هویت کلید(d &: سند، name: رشته، loc: رشته، param: رشته)

احراز هویت با کلید API در سرآیند، پرس‌وجو یا کوکی تعریف می‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

مسیر `Route`

تابع مسیر(d &: سند، method: رشته، pattern: رشته): صحیح

عملیاتی را برای روش و مسیر اضافه می‌کند، یا اگر هست انتخاب می‌کند، و شماره‌اش را برمی‌گرداند. پارامترهای :name مسیر خودکار ثبت می‌شوند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

انتخاب مسیر `At`

تابع انتخاب مسیر(d &: سند، method: رشته، pattern: رشته): منطقی

عملیات موجود را برای فراخوانی‌های بعدی انتخاب می‌کند؛ اگر نباشد نادرست است و آن فراخوانی‌ها چیزی را تغییر نمی‌دهند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

خلاصه `Summary`

تابع خلاصه(d &: سند، text: رشته)

خلاصه‌ی عملیات فعلی.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

جزئیات `Details`

تابع جزئیات(d &: سند، text: رشته)

توضیح کامل.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

برچسب `Tag`

تابع برچسب(d &: سند، name: رشته)

برچسبی برای گروه‌بندی در صفحه.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

شناسه عملیات `OperationId`

تابع شناسه عملیات(d &: سند، id: رشته)

شناسه‌ی یکتای عملیات، برای ابزارهای تولید کد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

منسوخ `Deprecated`

تابع منسوخ(d &: سند)

عملیات را منسوخ علامت می‌زند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

امن `Secure`

تابع امن(d &: سند، scheme: رشته)

احراز هویت تعریف‌شده را برای عملیات لازم می‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

پرسمان `Query`

تابع پرسمان(d &: سند، name: رشته، description: رشته، required: منطقی)

پارامتر پرس‌وجوی رشته‌ای.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

پرسمان نوع دار `QueryTyped`

تابع پرسمان نوع دار<T>(d &: سند، name: رشته، description: رشته، required: منطقی، sample: T)

پارامتر پرس‌وجو با گونه‌ای که از مقدار نمونه برداشته می‌شود.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

پرسمان گزینه ای `QueryEnum`

تابع پرسمان گزینه ای(d &: سند، name: رشته، description: رشته، required: منطقی، values: وکتور<رشته>)

پارامتر پرس‌وجو با مقدارهای مجاز.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

سرصفحه `Header`

تابع سرصفحه(d &: سند، name: رشته، description: رشته، required: منطقی)

پارامتر سرآیند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

کوکی `Cookie`

تابع کوکی(d &: سند، name: رشته، description: رشته، required: منطقی)

پارامتر کوکی.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

پارامتر مسیر `PathParam`

تابع پارامتر مسیر(d &: سند، name: رشته، description: رشته)

توضیح یک پارامتر مسیر.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

می پذیرد `Accepts`

تابع می پذیرد<T>(d &: سند، description: رشته، sample: T)

بدنه‌ی جیسون با طرحواره‌ی گونه‌ی نمونه.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

می پذیرد اختیاری `AcceptsOptional`

تابع می پذیرد اختیاری<T>(d &: سند، description: رشته، sample: T)

مثل تابع بالا، ولی بدنه اختیاری است.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

می پذیرد خام `AcceptsRaw`

تابع می پذیرد خام(d &: سند، description: رشته، content_type: رشته، schema: رشته، required: منطقی)

بدنه با نوع محتوا و طرحواره‌ای که خودتان می‌دهید.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

می پذیرد فرم `AcceptsForm`

تابع می پذیرد فرم<T>(d &: سند، description: رشته، sample: T)

بدنه‌ی فرم با فیلدهای گونه‌ی نمونه.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

برمی گرداند `Returns`

تابع برمی گرداند<T>(d &: سند، code: صحیح، description: رشته، sample: T)

پاسخ جیسون با کد و طرحواره‌ی یک مقدار نمونه؛ فراخوانی دوباره با همان کد جای قبلی را می‌گیرد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

برمی گرداند خام `ReturnsRaw`

تابع برمی گرداند خام(d &: سند، code: صحیح، description: رشته، content_type: رشته، schema: رشته)

پاسخ با نوع محتوا و طرحواره‌ی دلخواه.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

برمی گرداند متن `ReturnsText`

تابع برمی گرداند متن(d &: سند، code: صحیح، description: رشته)

پاسخ متنی.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

برمی گرداند اچ تی ام ال `ReturnsHtml`

تابع برمی گرداند اچ تی ام ال(d &: سند، code: صحیح، description: رشته)

پاسخ HTML.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

برمی گرداند پرونده `ReturnsFile`

تابع برمی گرداند پرونده(d &: سند، code: صحیح، description: رشته، content_type: رشته)

پاسخ پرونده با نوع محتوا.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

برمی گرداند سرصفحه `ReturnsHeader`

تابع برمی گرداند سرصفحه(d &: سند، code: صحیح، name: رشته، description: رشته)

سرآیندی را به پاسخ با این کد اضافه می‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

بدون بدنه برمی گرداند `ReturnsNothing`

تابع بدون بدنه برمی گرداند(d &: سند، code: صحیح، description: رشته)

پاسخ بدون بدنه، مثل ۲۰۴ یا ۴۰۴.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-http-swagger-Build.salam

سواگر net/http/swagger

مستند کردن API کنار مسیرهایش

طرح‌های احراز هویت و ذخیره‌ی مشخصات

بررسی مستندات در CI

سرو مستندات همراه API

گونه‌ها

پارامتر Param

پاسخ Reply

طرح احراز هویت Scheme

عملیات Op

تعریف Definition

سند Doc

پایاها و متغیرها

نوع جیسون JSON_TYPE

نوع متن TEXT_TYPE

نوع اچ تی ام ال HTML_TYPE

نوع فرم FORM_TYPE

طرحواره متن TEXT_SCHEMA

طرحواره دودویی BINARY_SCHEMA

تابع‌ها

پویش Scan

پویش با پیشوند ScanPrefix

صفحه Page

مشخصات Spec

مشخصات با تورفتگی SpecIndent

نصب Mount

نصب مشخصات MountSpec

سرو Serve

سرو مشخصات ServeSpec

مشخصات از پرونده SpecFromFile

نوشتن مشخصات WriteSpec

مشکلات Problems

توضیح داده نشده Undocumented

جا افتاده Missing

آزاد سازی Free

جدید New

توضیح Describe

سرور Server

تماس Contact

پروانه License

احراز هویت حامل BearerAuth

احراز هویت کلید ApiKeyAuth

مسیر Route

انتخاب مسیر At

خلاصه Summary

جزئیات Details

برچسب Tag

شناسه عملیات OperationId

منسوخ Deprecated

امن Secure

پرسمان Query

پرسمان نوع دار QueryTyped

پرسمان گزینه ای QueryEnum

سرصفحه Header

کوکی Cookie

پارامتر مسیر PathParam

می پذیرد Accepts

می پذیرد اختیاری AcceptsOptional

می پذیرد خام AcceptsRaw

می پذیرد فرم AcceptsForm

برمی گرداند Returns

برمی گرداند خام ReturnsRaw

برمی گرداند متن ReturnsText

برمی گرداند اچ تی ام ال ReturnsHtml

برمی گرداند پرونده ReturnsFile

برمی گرداند سرصفحه ReturnsHeader

بدون بدنه برمی گرداند ReturnsNothing

سواگر `net/http/swagger`

پارامتر `Param`

پاسخ `Reply`

طرح احراز هویت `Scheme`

عملیات `Op`

تعریف `Definition`

سند `Doc`

نوع جیسون `JSON_TYPE`

نوع متن `TEXT_TYPE`

نوع اچ تی ام ال `HTML_TYPE`

نوع فرم `FORM_TYPE`

طرحواره متن `TEXT_SCHEMA`

طرحواره دودویی `BINARY_SCHEMA`

پویش `Scan`

پویش با پیشوند `ScanPrefix`

صفحه `Page`

مشخصات `Spec`

مشخصات با تورفتگی `SpecIndent`

نصب `Mount`

نصب مشخصات `MountSpec`

سرو `Serve`

سرو مشخصات `ServeSpec`

مشخصات از پرونده `SpecFromFile`

نوشتن مشخصات `WriteSpec`

مشکلات `Problems`

توضیح داده نشده `Undocumented`

جا افتاده `Missing`

آزاد سازی `Free`

جدید `New`

توضیح `Describe`

سرور `Server`

تماس `Contact`

پروانه `License`

احراز هویت حامل `BearerAuth`

احراز هویت کلید `ApiKeyAuth`

مسیر `Route`

انتخاب مسیر `At`

خلاصه `Summary`

جزئیات `Details`

برچسب `Tag`

شناسه عملیات `OperationId`

منسوخ `Deprecated`

امن `Secure`

پرسمان `Query`

پرسمان نوع دار `QueryTyped`

پرسمان گزینه ای `QueryEnum`

سرصفحه `Header`

کوکی `Cookie`

پارامتر مسیر `PathParam`

می پذیرد `Accepts`

می پذیرد اختیاری `AcceptsOptional`

می پذیرد خام `AcceptsRaw`

می پذیرد فرم `AcceptsForm`

برمی گرداند `Returns`

برمی گرداند خام `ReturnsRaw`

برمی گرداند متن `ReturnsText`

برمی گرداند اچ تی ام ال `ReturnsHtml`

برمی گرداند پرونده `ReturnsFile`

برمی گرداند سرصفحه `ReturnsHeader`

بدون بدنه برمی گرداند `ReturnsNothing`