Swagger создает платформу управления документами API

Документация по API является основой для стыковки внешнего и внутреннего интерфейса, но если она все еще находится на стадии рукописной документации, это уже слишком. Возможно, вы пробовали различные инструменты управления интерфейсом API, такие как postman, apizza и т. д., но мне все равно неудобно пользоваться ими лично, в конечном итоге я отказываюсь.

С точки зрения создания и управления текущими документами API Swagger можно считать хорошей структурой. Сегодня я расскажу об использовании Swagger. Ниже в качестве примера используется веб-API .NETCore. Другие языки аналогичны и в конечном итоге полагаются на сгенерированный файл json/yaml.

генерация документа

встроенный код

1. Создайте новое веб-приложение ASP.NET Core, выберите тип API

2. Nuget устанавливает Swashbuckle.AspNetCore

   Install-Package Swashbuckle.AspNetCore
   

3. Добавьте код, связанный с Swagger, в ConfigureServices и методы Configure в Startup.cs.

   public void ConfigureServices(IServiceCollection services)
   {
   	services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
          
   	// swagger.json 文档生成参数配置
   	services.AddSwaggerGen(options =>
   	{
   		options.SwaggerDoc("v1", new Info
   		{
   			Title = "SwaggerTest接口文档",
   			Version = "1.0.0"
   		});
   		
   		options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "SwaggerTest.XML"));
   	});
   }
   

   public void Configure(IApplicationBuilder app, IHostingEnvironment env)
   {
   	if (env.IsDevelopment())
   	{
   		app.UseDeveloperExceptionPage();
   	}
   
   	app.UseMvc();
   
   	app.UseSwagger();
   	
   	// 通过SwaggerUI展示
   	app.UseSwaggerUI(options =>
   	{
   		options.SwaggerEndpoint("/swagger/v1/swagger.json", "SwaggerTest");
   	});
   }
   

4. "Создать" в свойствах проекта поставить галочку "XML файл документации" (Проверьте режимы отладки и выпуска.). Целью этого шага является создание документации из комментариев к коду, поэтому методы и параметры интерфейса должны быть полностью закомментированы.
   

5. запустить проект, посетитьhttp://localhost:62654/swagger/index.html
   

Вышеописанный метод очень прост в использовании, но лично я считаю, что есть следующие проблемы:

1. Некоторый код, связанный со Swagger, необходимо добавить в автозагрузку, что недостаточно чисто.

2. Если имеется несколько служб API, каждая служба должна добавить аналогичный код, а адрес документа каждой службы является независимым и не может управляться единообразно.

невстроенный код

Swagger UIЭто интерфейсный проект, который можно использовать в одиночку. Из конфигурации параметров UseSwaggerUI:

app.UseSwaggerUI(options =>
{
	options.SwaggerEndpoint("/swagger/v1/swagger.json", "SwaggerTest");
});

На самом деле вам нужно только сослаться на файл «/swagger/v1/swagger.json», поэтому есть только способ сгенерировать swagger.json в соответствии с dll-файлом проекта, а затем сослаться на сгенерированный swagger.json на Интерфейс Swagger.NSwagИменно для удовлетворения этой потребности.

Если оставить в стороне подход со встроенным кодом, скажем, это совершенно новый проект веб-API.

1. скачатьNSwag, загрузите инструменты командной строки NSwag в разделе «Загрузки». Например, после загрузки адрес распаковки будет таким: C:\Users\Administrator\Downloads\NSwag\

2. Создайте новый bat-файл в корневом каталоге проекта и добавьте скрипт, выполните и сгенерируйте swagger.json (среда окон)

   :: 生成的文档名，每个项目最好是唯一的
   SET FILE_NAME=swaggerTest
   :: 项目dll地址
   SET SOURCE_DLL=bin\Release\netcoreapp2.1\publish\SwaggerTest.dll
   :: 文档生成的目标文件夹
   SET TARGET_DIR=D:\ApiDoc\public\docs\
   
   :: Swagger文档配置
   
   :: 标题
   SET TITLE=SwaggerTest接口文档
   :: 描述
   SET DESCRIPTION=SwaggerTest接口文档描述
   :: 版本
   SET VERSION=1.0.0
   :: 接口测试请求的host地址，不同的api服务有不同的host
   SET HOST=localhost:5000
   
   :: 通过 dotnet-nswag 执行生成命令
   dotnet C:\Users\Administrator\Downloads\NSwag\NetCore21\dotnet-nswag.dll webapi2swagger /assembly:"%SOURCE_DLL%" /AspNetCore:true /output:%TARGET_DIR%%FILE_NAME%.json /InfoTitle:"%TITLE%" /InfoDescription:"%DESCRIPTION%" /InfoVersion:%VERSION% /ServiceHost:%HOST%
   

После выполнения bat-скрипта в каталоге D:\ApiDoc\public\docs\ появится дополнительный файл swaggerTest.json, поэтому нам не нужно модифицировать какой-либо код. Пока есть файл json, соответствующий документу API, и следующим шагом будет его отображение через пользовательский интерфейс Swagger. Если предположить, что каждый проект API создает файл json для указанного каталога, а сам пользовательский интерфейс Swagger поддерживает конфигурацию нескольких URL-адресов документов, это означает, что можно создать платформу управления документами API.

управление документами

1. скачатьSwagger UIи распаковать

2. Собрать проект Node.js, можно использовать фреймворк Express или Koa (также доступны проекты на других языках, любой на выбор)

   1. Скопируйте все файлы в папке Swagger-Ui Dist к общедоступной папке проекта

   2. установить экспресс

   3. Создайте новый index.js и добавьте следующий код

      const express = require('express');
      const app = express();
      
      app.use('/', express.static('public'));
      
      app.listen(3000, function () {
      	console.log('app listening on http://localhost:3000');
      });
      

   4. запустить службу

      node index.js
      

После выполнения вышеуказанных шагов сайт пользовательского интерфейса Swagger будет готов, посетитеhttp://localhost:3000Появится страница документации интерфейса API по умолчанию.

Откройте public/index.html, и вы найдете этот фрагмент кода:

const ui = SwaggerUIBundle({
	url: "https://petstore.swagger.io/v2/swagger.json",
	...
})

URL здесь сконфигурирован с помощью адреса файла файлов по умолчанию.

const ui = SwaggerUIBundle({
    url: "./docs/swaggerTest.json",
    ...
})

Если имеется несколько файлов json, параметр url использовать нельзя, и его необходимо изменить на параметр urls. Подробнее см.Конфигурация параметров пользовательского интерфейса Swagger, чтобы не нужно было каждый раз вручную настраивать URL-адреса, необходимо динамически читать файлы в папке docs, а сгенерированные документы нужно только загрузить в этот каталог для просмотра и проверки напрямую.

Добавьте интерфейс в index.js:

app.get('/getDocs', function (req, res) {
    let docFileInfos = [];
    let pathDir = __dirname + '/public/docs';
    try {
        let fileNames = fs.readdirSync(pathDir);
        fileNames.forEach(function (fileName) {
            let data = fs.readFileSync(pathDir + '/' + fileName, 'utf8');
            data = data.trim();
            let json = JSON.parse(data);
            docFileInfos.push({
                url: './docs/' + fileName,
                name: json.info.title
            });
        });
    } catch (err) {
        console.log(err);
    }
    res.send(docFileInfos);
});

public/index.html вводит axios, вызывает интерфейс getDocs для получения результата и присваивает response.data параметру urls SwaggerUIBundle.

axios.get('/getDocs')
	.then(function (response) {
		if (response.status === 200 && response.data.length) {
			...
		}
	});

При наличии нескольких файлов json вы можете переключиться из раскрывающегося списка.

Ссылка на ссылку

• NSwag
• Swagger UI
• SwaggerSample
• APIDocSample