swagger ui express

Swagger UI Express

البيانات	الفروع	وظائف	خطوط

تتيح لك هذه الوحدة تقديم مستندات واجهة برمجة تطبيقات Swagger-UI التي تم إنشاؤها تلقائيًا من Express ، استنادًا إلى ملف swagger.json . والنتيجة هي وثائق المعيشة لواجهة برمجة التطبيقات الخاصة بك المستضافة من خادم API الخاص بك عبر مسار.

يتم سحب نسخة Swagger من NPM Module Swagger-Ui-Dist. يرجى استخدام ملف قفل أو تحديد إصدار Swagger-Ui-Dist الذي تريد التأكد من أنه متسق عبر البيئات.

قد تكون مهتمًا أيضًا بـ:

• Swagger-JSDOC: يسمح لك بتوحيد الطرق مع تعليقات JSDOC. ثم ينتج تكوين YML الكامل بشكل ديناميكي ، والذي يمكنك نقله إلى هذه الوحدة لإنتاج الوثائق. انظر أدناه تحت قسم الاستخدام لمزيد من المعلومات.
• أدوات Swagger: أدوات مختلفة ، بما في ذلك Swagger Editor و Swagger Code Gen وما إلى ذلك.

الاستخدام

التثبيت باستخدام NPM:

$ npm install swagger-ui-express

Express Setup app.js

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument ) ) ;

أو إذا كنت تستخدم جهاز التوجيه السريع

 const router = require ( 'express' ) . Router ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

router . use ( '/api-docs' , swaggerUi . serve ) ;
router . get ( '/api-docs' , swaggerUi . setup ( swaggerDocument ) ) ;

افتح http: // <app_host> : <app_port> /api-docs في متصفحك لعرض الوثائق.

إذا كنت ترغب في إعداد التوجيه استنادًا إلى مستند Swagger Checkout Swagger-Express-Router

Swagger-jsdoc

إذا كنت تستخدم Swagger-JSDOC ، فما عليك سوى تمرير Swaggerspec إلى وظيفة الإعداد:

 // Initialize swagger-jsdoc -> returns validated swagger spec in json format
const swaggerSpec = swaggerJSDoc ( options ) ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerSpec ) ) ;

مستكشف Swagger

افتراضيًا ، يتم إخفاء شريط Swagger Explorer ، لعرضه على True كخاصية "Explorer" للخيارات إلى وظيفة الإعداد:

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  explorer : true
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

خيارات التباهي المخصصة

لتمرير خيارات مخصصة ، على سبيل المثال ، إلى عميل Swaggerui ، تمرير كائن كخاصية "SwaggerOptions" للخيارات إلى وظيفة الإعداد:

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  swaggerOptions : {
    validatorUrl : null
  }
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

لجميع الخيارات المتاحة ، راجع تكوين واجهة المستخدم Swagger

أنماط CSS المخصصة

لتخصيص نمط صفحة Swagger ، يمكنك تمرير CSS المخصصة كخاصية "CustomCSS" للخيارات إلى وظيفة الإعداد.

على سبيل المثال لإخفاء رأس Swagger:

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customCss : '.swagger-ui .topbar { display: none }'
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

أنماط CSS المخصصة من URL

يمكنك أيضًا تمرير عنوان URL إلى ملف CSS المخصص ، يجب أن تكون القيمة عنوان URL العام للملف ويمكن أن تكون نسبية أو مطلقة لمسار Swagger.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customCssUrl : '/custom.css'
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

يمكنك أيضًا تمرير مجموعة من عناوين URL CSS لتحميل ملفات CSS متعددة.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customCssUrl : [
    '/custom.css' ,
    'https://example.com/other-custom.css'
  ]
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

مخصصة JS

إذا كنت ترغب في التحكم الكامل في HTML الخاص بك ، فيمكنك توفير ملف JavaScript الخاص بك ، فإن القيمة تقبل المسار المطلق أو النسبي. يجب أن تكون القيمة عنوان URL العام لملف JS.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customJs : '/custom.js'
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

يمكنك أيضًا تمرير مجموعة من عناوين URL JS لتحميل ملفات JS متعددة.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customJs : [
    '/custom.js' ,
    'https://example.com/other-custom.js'
  ]
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

من الممكن أيضًا إضافة javaScript inline ، إما كسلسلة أو صفيف من السلسلة.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customJsStr : 'console.log("Hello World")'
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ; 

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customJsStr : [
    'console.log("Hello World")' ,
    `
    var x = 1
    console.log(x)
    `
  ]
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

تحميل التباهي من عنوان URL

لتحميل Swagger الخاص بك من عنوان URL بدلاً من حقن المستند ، تمرير null كمعلمة الأولى ، وتمرير عنوان URL النسبي أو المطلق باعتباره خاصية "url" إلى "SwaggerOptions" في وظيفة الإعداد.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;

var options = {
  swaggerOptions : {
    url : 'http://petstore.swagger.io/v2/swagger.json'
  }
}

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( null , options ) ) ;

لتحميل مستندات Swagger متعددة من عناوين URL كقطعة منسدلة في شريط Explorer ، تمرير مجموعة من الكائنات ذات name وعنوان url إلى خاصية "عناوين URL" إلى "SwaggerOptions" في وظيفة الإعداد.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;

var options = {
  explorer : true ,
  swaggerOptions : {
    urls : [
      {
        url : 'http://petstore.swagger.io/v2/swagger.json' ,
        name : 'Spec1'
      } ,
      {
        url : 'http://petstore.swagger.io/v2/swagger.json' ,
        name : 'Spec2'
      }
    ]
  }
}

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( null , options ) ) ;

تأكد من تعيين خيار "Explorer" على "True" في خيارات الإعداد الخاصة بك حتى يكون المنسدلة مرئية.

تحميل Swagger من ملف Yaml

لتحميل ملف YAML لمواصفات Swagger الخاصة بك ، تحتاج إلى استخدام وحدة نمطية قادرة على تحويل YAML إلى JSON ؛ على سبيل المثال yaml .

 npm install yaml

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const fs = require ( "fs" )
const YAML = require ( 'yaml' )

const file  = fs . readFileSync ( './swagger.yaml' , 'utf8' )
const swaggerDocument = YAML . parse ( file )

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument ) ) ;

تعديل ملف Swagger أثناء الطيران قبل التحميل

لتعيين المضيف ديناميكيًا ، أو أي محتوى آخر ، في ملف Swagger استنادًا إلى كائن الطلب الوارد ، يمكنك تمرير JSON عبر كائن REQ ؛ لتحقيق ذلك ، لا تمرر Swagger JSON إلى وظيفة الإعداد وسيبحث عن swaggerDoc في كائن req .

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = { }

app . use ( '/api-docs' , function ( req , res , next ) {
    swaggerDocument . host = req . get ( 'host' ) ;
    req . swaggerDoc = swaggerDocument ;
    next ( ) ;
} , swaggerUi . serveFiles ( swaggerDocument , options ) , swaggerUi . setup ( ) ) ;

اثنين من وثائق تباهي

لتشغيل 2 مثيلات واجهة المستخدم مع مستندات Swagger مختلفة ، استخدم وظيفة ServiceFiles بدلاً من وظيفة الخدمة. وظيفة serviles لها نفس توقيع وظيفة الإعداد.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocumentOne = require ( './swagger-one.json' ) ;
const swaggerDocumentTwo = require ( './swagger-two.json' ) ;

var options = { }

app . use ( '/api-docs-one' , swaggerUi . serveFiles ( swaggerDocumentOne , options ) , swaggerUi . setup ( swaggerDocumentOne ) ) ;

app . use ( '/api-docs-two' , swaggerUi . serveFiles ( swaggerDocumentTwo , options ) , swaggerUi . setup ( swaggerDocumentTwo ) ) ;

app . use ( '/api-docs-dynamic' , function ( req , res , next ) {
  req . swaggerDoc = swaggerDocument ;
  next ( ) ;
} , swaggerUi . serveFiles ( ) , swaggerUi . setup ( ) ) ;

رابط إلى مستند Swagger

لتقديم رابط إلى مستند Swagger للتنزيل داخل واجهة المستخدم Swagger - ثم يقدم مستند Swagger كنقطة نهاية واستخدم خيار URL للإشارة إليه:

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
    swaggerOptions : {
        url : "/api-docs/swagger.json" ,
    } ,
}
app . get ( "/api-docs/swagger.json" , ( req , res ) => res . json ( swaggerDocument ) ) ;
app . use ( '/api-docs' , swaggerUi . serveFiles ( null , options ) , swaggerUi . setup ( null , options ) ) ; 

متطلبات

• العقدة v0.10.32 أو أعلى
• عبر 4 أو أعلى

الاختبار

• تثبيت فانتوم
• npm install
• npm test