public FileResult ExportApiWord(string type, string version)
{
string memi = string.Empty;
string fileExten = string.Empty;
Stream outdata = null;
//获取swagger json 之前通过swagger的接口获取，废弃了。原因：他返回的数据看着像json数据，实则不是，不能用newtonsoft反序列化成对象。
//var url = $"{HttpContext.Request.Scheme}://{HttpContext.Request.Host}/swagger/v2/swagger.json";
//var data = RestSharpHelper.HttpGet(url);
//var model = JsonHelper.StrToModel<OpenApiDocument>(data);
//1.获取api文档json，version是版本，根据指定版本获取指定版本的json对象。
var model = _swaggerGenerator.GetSwagger(version);
if (model == null)
{
throw new Exception("Swagger Json cannot be equal to null！");
}
//2.这里使用了微软的mvc模板引擎技术来生成html，做过mvc项目的同学应该都知道是啥东西，这里不细说了。自己看代码吧，用起来很方便。
var html = T4Helper.GeneritorSwaggerHtml($"{_hostingEnvironment.WebRootPath}\\SwaggerDoc.cshtml", model);
//3.将html转换成需要导出的文件类型。
var op = _spireDocHelper.SwaggerHtmlConvers(html, type, out memi);
if (!op.Successed)
{
throw new Exception(op.Message);
}
outdata = op.Data;
return(File(outdata, memi, $"Titan.Blog.WebAPP API文档 {version}{type}"));//返回文件流，type是文件格式
}
public static void Init(TestContext testContext)
{
var options = new SwaggerGeneratorSettings();
options.DocInclusionPredicate = (version, api) => true;
options.OperationFilters.Add(new RemoveReadOnlyFromUriParametersOperationFilter());
options.OperationFilters.Add(new RemoveBindNoneFromUriParametersOperationFilter());
options.OperationFilters.Add(new AddAsObjectAnnotationOperationFilter());
options.OperationFilters.Add(new HandleGridViewDataSetReturnType());
options.SwaggerDocs.Add("v1", new Info()
{
Title = "Test API", Version = "v1"
});
var serviceCollection = new ServiceCollection()
.AddSingleton <ObjectPoolProvider, DefaultObjectPoolProvider>()
.AddSingleton <IHostingEnvironment, HostingEnvironment>()
.AddLogging();
serviceCollection.AddMvc(setup => {
setup.Conventions.Add(new ApiExplorerVisibilityEnabledConvention());
})
.AddApplicationPart(typeof(CompaniesController).Assembly);
var serviceProvider = serviceCollection.BuildServiceProvider();
var apiDescriptionGroupCollectionProvider = serviceProvider.GetService <IApiDescriptionGroupCollectionProvider>();
var schemaRegistryFactory = new SchemaRegistryFactory(new JsonSerializerSettings(), new SchemaRegistrySettings());
var generator = new SwaggerGenerator(apiDescriptionGroupCollectionProvider, schemaRegistryFactory, options);
document = generator.GetSwagger("v1");
}
public static void Init(TestContext testContext)
{
var t = typeof(CompaniesController);
var config = new HttpConfiguration();
config.MapHttpAttributeRoutes();
config.EnsureInitialized();
var apiExplorer = new ApiExplorer(config);
var settings = new JsonSerializerSettings();
var versions = new Dictionary <string, Info> {
{ "v1", new Info()
{
version = "v1", title = "Test API"
} }
};
var options = new SwaggerGeneratorOptions(operationFilters: new IOperationFilter[]
{
// default filters used by Swashbuckle
new HandleFromUriParams(),
new ApplySwaggerOperationAttributes(),
new ApplySwaggerResponseAttributes(),
new ApplySwaggerOperationFilterAttributes(),
// our custom filters
new AddAsObjectAnnotationOperationFilter(),
new HandleGridViewDataSetReturnType()
});
var generator = new SwaggerGenerator(apiExplorer, settings, versions, options);
document = generator.GetSwagger("http://localhost:61453/", "v1");
}
public IActionResult GetSwDocByPath()
{
var document = SwaggerGenerator.GetSwagger("v1");
var stream = GeneratorWordDoc.Generator(document, out var memi, "Templates\\SwaggerDoc.cshtml");
return(File(stream, memi, "api简化文档.doc"));
}
public IActionResult GetSwDoc()
{
var document = SwaggerGenerator.GetSwagger("v1");
var stream = GeneratorWordDoc.Generator(document, out var memi);
return(File(stream, memi, "api简化文档.doc"));
}
/// <inheritdoc/>
public OpenApiDocument GetSwagger(string documentName, string host = null, string basePath = null)
{
foreach (var handler in _handlers)
{
if ($"Dolittle.{handler.Name}".Equals(documentName, StringComparison.InvariantCultureIgnoreCase))
{
var document = _documentGenerator.GenerateFor(handler);
var path = basePath == null ? PathString.Empty : (PathString)basePath;
var serverPath = path.Add(_options.Value.BasePath).Add($"/{handler.Name}");
document.Servers = new[]
{
new OpenApiServer
{
Url = $"{host}{serverPath}"
}
};
foreach (var modifier in _modifiers)
{
modifier.ModifyDocument(handler, document);
}
return(document);
}
}
return(_swaggerGenerator.GetSwagger(documentName, host, basePath));
}
public static void Init(TestContext testContext)
{
var knownTypesOptions = Options.Create(new DotvvmApiOptions());
knownTypesOptions.Value.AddKnownType(typeof(Company <string>));
var options = new SwaggerGeneratorOptions
{
DocInclusionPredicate = (version, api) => true,
OperationFilters =
{
new RemoveReadOnlyFromUriParametersOperationFilter(),
new RemoveBindNoneFromUriParametersOperationFilter(),
new AddAsObjectOperationFilter(knownTypesOptions)
},
DocumentFilters =
{
new HandleKnownTypesDocumentFilter(knownTypesOptions)
},
SwaggerDocs =
{
{ "v1", new Info()
{
Title = "Test API", Version = "v1"
} }
}
};
var serviceCollection = new ServiceCollection()
.AddSingleton <ObjectPoolProvider, DefaultObjectPoolProvider>()
.AddSingleton <IHostingEnvironment, HostingEnvironment>()
.AddSingleton <DiagnosticSource>(p => new DiagnosticListener("test"))
.AddLogging();
serviceCollection.AddMvc(setup => setup.Conventions.Add(new ApiExplorerVisibilityEnabledConvention()))
.AddApplicationPart(typeof(CompaniesController).Assembly);
var serviceProvider = serviceCollection.BuildServiceProvider();
var apiDescriptionGroupCollectionProvider = serviceProvider.GetRequiredService <IApiDescriptionGroupCollectionProvider>();
var schemaSettings = new SchemaRegistryOptions()
{
SchemaFilters =
{
new AddTypeToModelSchemaFilter()
}
};
var schemaRegistryFactory = new SchemaRegistryFactory(new JsonSerializerSettings(), schemaSettings);
var generator = new SwaggerGenerator(apiDescriptionGroupCollectionProvider, schemaRegistryFactory, options);
document = generator.GetSwagger("v1");
}
public FileResult ExportWord(string type, string version)
{
string contenttype = string.Empty;
var model = _swaggerGenerator.GetSwagger(version); //1. 根据指定版本获取指定版本的json对象。
var html = HtmlHelper.GeneritorSwaggerHtml($"{_webHostEnvironment.WebRootPath}\\SwaggerDoc.cshtml", model); //2. 根据模板引擎生成html
var op = _spireDocHelper.SwaggerConversHtml(html, type, out contenttype); //3.将html导出文件类型
return(File(op, contenttype, $"XUnit.Core接口文档{type}"));
}
public void GetSwagger_SupportsOption_SchemaFilters()
{
var subject = new SwaggerGenerator(
new SwaggerGeneratorOptions
{
SwaggerDocs = new Dictionary <string, OpenApiInfo>
{
["v1"] = new OpenApiInfo {
Version = "V1", Title = "Test API"
}
}
},
new FakeApiDescriptionGroupCollectionProvider(new[]
{
ApiDescriptionFactory.Create <FakeController>(
c =>
nameof(c.ActionWithObjectParameter),
groupName: "v1",
httpMethod: "POST",
relativePath: "resource",
parameterDescriptions: new []
{
new ApiParameterDescription
{
Name = "param",
Source = BindingSource.Body
}
})
}),
new SchemaGenerator(new SchemaGeneratorOptions
{
SchemaFilters = new List <ISchemaFilter>
{
new VendorExtensionsSchemaFilter()
}
}, new SystemTextJsonBehavior(new JsonSerializerOptions()))
);
var document = subject.GetSwagger("v1");
Assert.Equal(2, document.Components.Schemas["XmlAnnotatedType"].Extensions.Count);
Assert.Equal("bar", ((OpenApiString)document.Components.Schemas["XmlAnnotatedType"].Extensions["X-foo"]).Value);
Assert.Equal("v1", ((OpenApiString)document.Components.Schemas["XmlAnnotatedType"].Extensions["X-docName"]).Value);
}
/// <summary>
/// Generate swagger doc
/// </summary>
/// <param name="httpConfig"></param>
public static void SaveSwaggerJsonDoc(this HttpConfiguration httpConfig)
{
var baseAddress = $"{Properties.Settings.Default.ServiceUrl}:{Properties.Settings.Default.ServicePort}/";
// 1) Apply your WebApi config.
//WebApiConfig.Register(httpConfig);
httpConfig.EnsureInitialized();
// 2) Generate in-memory swagger doc
var swaggerProvider = new SwaggerGenerator(
httpConfig.Services.GetApiExplorer(),
httpConfig.Formatters.JsonFormatter.SerializerSettings,
new Dictionary <string, Info> {
{ "v1", new Info {
version = "v1", title = "Push Notify"
} }
},
new SwaggerGeneratorOptions(
// apply your swagger options here ...
schemaIdSelector: (type) => type.FriendlyId(true),
conflictingActionsResolver: (apiDescriptions) => apiDescriptions.First()
)
);
var swaggerDoc = swaggerProvider.GetSwagger(baseAddress, "v1");
// 3) Serialize
var swaggerString = JsonConvert.SerializeObject(
swaggerDoc,
Formatting.Indented,
new JsonSerializerSettings
{
NullValueHandling = NullValueHandling.Ignore,
Converters = new[] { new VendorExtensionsConverter() }
}
);
if (!File.Exists(GetPath()))
{
File.Delete(GetPath());
}
File.WriteAllText(GetPath(), swaggerString);
}
public OpenApiDocument GetSwagger(string documentName, string host = null, string basePath = null)
{
// Just catch document name
_documentName = documentName;
return(_swaggerGenerator.GetSwagger(documentName, host, basePath));
}
public static void Init(TestContext testContext)
{
var knownTypesOptions = Options.Create(new DotvvmApiOptions());
knownTypesOptions.Value.AddKnownType(typeof(Company <string>));
var options = new SwaggerGeneratorOptions
{
DocInclusionPredicate = (version, api) => true,
OperationFilters =
{
new RemoveReadOnlyFromUriParametersOperationFilter(),
new RemoveBindNoneFromUriParametersOperationFilter(),
new AddAsObjectOperationFilter(knownTypesOptions)
},
DocumentFilters =
{
new HandleKnownTypesDocumentFilter(knownTypesOptions)
},
SwaggerDocs =
{
{ "v1", new OpenApiInfo()
{
Title = "Test API", Version = "v1"
} }
}
};
var serviceCollection = new ServiceCollection()
.AddSingleton <ObjectPoolProvider, DefaultObjectPoolProvider>()
.AddSingleton <DiagnosticSource>(p => new DiagnosticListener("test"))
.AddLogging();
serviceCollection.AddMvc(setup => setup.Conventions.Add(new ApiExplorerVisibilityEnabledConvention()))
.AddApplicationPart(typeof(CompaniesController).Assembly);
var serviceProvider = serviceCollection.BuildServiceProvider();
var apiDescriptionGroupCollectionProvider = serviceProvider.GetRequiredService <IApiDescriptionGroupCollectionProvider>();
string GetCustomSchemaId(Type modelType)
{
if (!modelType.IsConstructedGenericType)
{
return(modelType.Name.Replace("[]", "Array"));
}
var generics = modelType.GetGenericArguments()
.Select(genericArg => GetCustomSchemaId(genericArg))
.Aggregate((previous, current) => previous + current);
return($"{modelType.Name.Split('`').First()}[{generics}]");
}
var schemaGeneratorOptions = new SchemaGeneratorOptions()
{
SchemaFilters =
{
new AddTypeToModelSchemaFilter()
},
SchemaIdSelector = type => GetCustomSchemaId(type)
};
var schemaGenerator = new SchemaGenerator(schemaGeneratorOptions, new JsonSerializerDataContractResolver(new JsonSerializerOptions()));
var swaggerGenerator = new SwaggerGenerator(options, apiDescriptionGroupCollectionProvider, schemaGenerator);
document = swaggerGenerator.GetSwagger("v1");
}
/// <summary>
/// 获取Swagger文档
/// </summary>
/// <param name="documentName">文档名称</param>
/// <param name="host">主机</param>
/// <param name="basePath">基础路径</param>
public OpenApiDocument GetSwagger(string documentName, string host, string basePath) =>
Cache.GetOrAdd($"{documentName}_{host}_{basePath}",
(_) => _swaggerGenerator.GetSwagger(documentName, host, basePath));
/// <summary>
/// 生成MarkDown
/// </summary>
/// <returns></returns>
public string GetSwaggerDoc(string name)
{
if (string.IsNullOrEmpty(name))
{
throw new Exception("name is null !");
}
var document = _generator.GetSwagger(name);
if (document == null)
{
throw new Exception("document is null !");
}
Schemas = document.Components.Schemas;
var markDown = new StringBuilder();
markDown.AppendLine(document?.Info?.Title.H()); //文档标题
markDown.AppendLine(document?.Info?.Description.Ref()); //文档描述
foreach (var path in document.Paths)
{
foreach (var operationItem in path.Value.Operations)
{
var operation = operationItem.Value;
var method = operationItem.Key.ToString();
var row = new StringBuilder();
var url = path.Key;
var title = operation.Summary ?? url;
var query = GetParameters(operation.Parameters);
var(requestExapmle, requestSchema) = GetRequestBody(operation.RequestBody);
var(responseExapmle, responseSchema) = GetResponses(operation.Responses);
row.AppendLine(title.H(2)); //接口名称
row.AppendLine("基本信息".H(3).NewLine()); //基本信息
row.AppendLine($"{"接口地址：".B()}{url}".Li().NewLine());
row.AppendLine($"{"请求方式：".B()}{method}".Li().NewLine());
if (method == "Post" || method == "Put")
{
row.AppendLine($"{"请求类型：".B()}{contentType}".Li().NewLine());
}
if (string.IsNullOrWhiteSpace(query) == false)//Query
{
row.AppendLine("Parameters".H(3));
row.AppendLine(query);
}
if (string.IsNullOrWhiteSpace(requestSchema) == false)//RequestSchema
{
row.AppendLine("Request Schema".H(3));
row.AppendLine(requestSchema.Code());
}
if (string.IsNullOrWhiteSpace(requestExapmle) == false)//RequestBody
{
row.AppendLine("RequestBody Example".H(3));
row.AppendLine(requestExapmle.Code());
}
if (string.IsNullOrWhiteSpace(responseSchema) == false)//ResponseSchema
{
row.AppendLine("Response Schema".H(3));
row.AppendLine(responseSchema.Code());
}
if (string.IsNullOrWhiteSpace(responseExapmle) == false)//ResponseBody
{
row.AppendLine("ResponseBody Example".H(3));
row.AppendLine(responseExapmle.Code());
}
if (string.IsNullOrWhiteSpace(row.ToString()) == false)
{
markDown.AppendLine(row.ToString().Br());
}
}
}
return(markDown.ToString());
}
public OpenApiDocument GetSwagger(string documentName, string host = null, string basePath = null)
{
return(SwaggerCache.Get(documentName, (_) => _swaggerGenerator.GetSwagger(documentName, host, basePath)));
}
