如何使用Markdown在Swagger模型描述中工作?
问题描述:
我正试图在Swagger中为模型项添加额外的信息。该文档说GFM语法可以用在描述字段中,但这不适用于所有地方。如何使用Markdown在Swagger模型描述中工作?
这是问题的一个最小虚拟例如:
swagger: '2.0'
info:
title: Example API
description: (1) This is the API description containing some *rich* **text**
version: "1.0.0"
paths:
/products:
get:
summary: Product Types
description: (2) This is the path description also containing some *rich* **text**
responses:
200:
description: (3) This is a response description also containing some *rich* **text**
schema:
type: array
items:
$ref: '#/definitions/Product'
definitions:
Product:
description: (4) This is a model description where *rich* **text** does not work
type: object
properties:
product_id:
type: string
description: (5) This is a field description where *rich* **text** does not work
的schema object documentation说,我应该能够在标记为(4)之上,但没有地方用降价说一下地方(5)。
我想将Markdown添加到模型部分中两个位置中的任意一个。我怎样才能使这个工作?
答
Swagger编辑器在模型描述中不支持Markdown。从https://github.com/swagger-api/swagger-editor/issues/682:
对于渲染JSON Schema对象,我们使用的是不支持Markdown的json-schema-view-js lib。 Swagger编辑器不能改变这个库的行为,这种行为并不常见于添加到库中。
如果你需要这个功能,你可以叉swagger-editor和/或json-schema-view-js和执行功能/修复自己,然后提交pull请求。
请参阅https://github.com/swagger-api/swagger-editor/issues/682:“为了呈现JSON Schema对象,我们正在使用[json-schema-view-js](https://github.com/mohsen1/json-schema-view-js)不支持Markdown的lib,Swagger Editor不能改变这个lib的行为,这种行为不是常见的添加到lib中的。 – Helen
@Helen谢谢你。这是我确切的问题,但比我做得更简洁:)他们应该真正更新他们的文档,以便正确或更少误导。 –
这是编辑器的问题,因为它没有完全实现Swagger规范的这一部分。规范是一个规范,取决于工具开发人员的实现。 – Helen