api响应泛型参数swagger_OpenAPI规范和Swagger简介OpenAPI是⽤于描述REST API的规范。您可以将OpenAPI规范视为DITA规范。使⽤DITA，有⼀些⽤于定义帮助组件的特定XML元素，以及这些元素的必需顺序和层次结构。不同的⼯具可以读取DITA并从该信息中建⽴⽂档⽹站。使⽤OpenAPI(⽽不是XML)，您可以拥有⼀组JSON对象，它们具有定义其命名，顺序和内容的特定架构。此JSON⽂件(通常⽤YAML⽽不是JSON表⽰)描述了API的每个部分。通过以标准格式描述API，发布⼯具可以以编程⽅式解析有关API的信息，并以风格化的交互式显⽰⽅式显⽰每个组件。
⽬录
浏览OpenAPI规范
验证规格
通过代码注释⾃动⽣成OpenAPI⽂件
另⼀种⽅法：规范优先开发
技术规范作者的⾓⾊
使⽤Swagger UI呈现您的OpenAPI规范
活动：通过Petstore演⽰
探索Swagger UI其他阅读OpenAPI规范的⼯具
⾃定义Swagger UI
OpenAPI和Swagger UI的缺点
⼀些安慰
资源和进⼀步阅读
浏览OpenAPI规范
为了更好地理解OpenAPI规范，让我们看⼀下⼀些规范摘录。我们将在即将到来的教程中更深⼊地研究每个元素。
此处的Github存储库中提供了OpenAPI规范的正式描述。⼀些OpenAPI元素是路径，参数，响应和安全性。这些元素都是⼀个JSON对象，其中包含⼀些属性和数组。
在OpenAPI规范中，端点是路径。如果您有⼀个称为“ pets”的端点，则此端点的OpenAPI规范可能如
下所⽰：
此YAML代码来⾃Swagger Petstore演⽰。
这些对象的含义如下：
/ pets是端点路径。
get 是HTTP⽅法。
parameters 列出了端点的参数。
responses 列出了请求的响应。
200 是HTTP状态代码。
$ ref 是对实现的另⼀部分的引⽤，其中定义了响应(在组件中)。OpenAPI有很多这样的$ ref引⽤，以保持代码⼲净并促进重⽤。
验证规格
在编写OpenAPI规范⽂档时，可以在Swagger编辑器中编写代码，⽽⽆需在⽂本编辑器中⼯作。Swagger编辑器会动态验证您的内容，以确定您创建的规范⽂档是否有效。
Swagger编辑器会动态验证您的规范内容，并在右侧显⽰您的显⽰
在Swagger编辑器中进⾏编码时，如果您出错了，则可以在继续之前快速修复它，⽽不必等到以后再运⾏构建并解决错误。
对于规范⽂档的格式，可以选择使⽤JSON或YAML。先前的代码⽰例在YAML中。YAML指的是“ YAM
L不是标记语⾔”，这意味着YAML没有任何标记标签(<>)，这与XML等其他标记语⾔很常见。
YAML取决于间距和冒号来建⽴对象语法。这种对空间敏感的格式使代码更易于阅读，但有时正确设置间距也⽐较棘⼿。
通过代码注释⾃动⽣成OpenAPI⽂件
除了⼿动编写OpenAPI规范⽂档外，您还可以从编程代码中的注释⾃动⽣成它。如果您拥有⼤量的API，或者对于技术编写者⽽⾔，创建此⽂档不切实际，则这种以开发⼈员为中⼼的⽅法可能有意义。
Swagger提供了各种库，您可以将它们添加到编程代码中以⽣成规范⽂档。然后，这些Swagger库解析开发⼈员添加的注释并⽣成OpenAPI规范⽂档。这些库被视为Swagger Codegen项⽬的⼀部分。注释⽅法因编程语⾔⽽异。例如，这是有关使⽤Swagger for Scalatra注释代码的教程。有关Codegen的更多信息，请参阅API Evangelist的Swagger⾃动API代码⽣成⼯具⽐较。有关其他⼯具和库，请参见Swagger服务和⼯具和开源集成。
尽管这种⽅法可以“⾃动”⽣成规范，但是仍然有⼈必须知道要添加哪些注释以及如何添加注释(此过程与Javadoc的注释和注释不太相似)。然后，有⼈必须为每个注释的值(描述端点，参数等)编写内容。简⽽⾔之，这个过程并⾮没有花⼒，⾃动化的部分是让Codegen库⽣成模型定义和符合OpenAPI架构的有效规范⽂档。
尽管如此，许多开发⼈员仍对这种⽅法感到兴奋，因为它提供了⼀种从代码注释⽣成⽂档的⽅法，这是开发⼈员多年来与其他编程语⾔(例如Java(使⽤Javadoc)或C ++(使⽤Doxygen))⼀起所做的事情。他们通常认为从代码⽣成⽂档可以减少⽂档漂移。如果⽂档与代码紧密结合，则⽂档可能会保持最新状态。
如果⾛这条路，请确保可以访问源代码以对注释进⾏编辑。否则，您的开发⼈员将编写您的⽂档(虽然很好，但通常会导致结果不佳)。
另⼀种⽅法：规范优先开发
尽管您可以从代码注释中⽣成规范⽂档，但许多⼈认为⾃动⽣成并不是最佳⽅法。Michael Stowe在《不受⼲扰的REST：完美API设计指南》中，建议团队⼿动实施规范，然后将规范⽂档视为开发⼈员在进⾏实际编码时使⽤的合同。这种⽅法通常称为“规范优先开发”。
规范优先开发是关于如何更有效地开发API的理念。如果您遵循规范优先的原则，那么您将⾸先编写规范并将其⽤
换句话说，开发⼈员请查阅规范⽂档，以了解应调⽤的参数名称，响应的名称，等等。确⽴了此“合同”或“蓝图”之后，Stowe说您可以将注释放⼊代码中(如果需要)，从⽽以更⾃动化的⽅式⽣成规范⽂档。但是在没有规格之前不要编码。
很多时候，开发团队会迅速跳转到对API端点，参数和响应进⾏编码的过程，⽽⽆需进⾏⼤量的⽤户测试或研究API是否符合⽤户的需求。由于版本控制API⾮常困难(您必须⽀持每个新版本都必须具有与先前版本完全向后兼容的功能)，因此您要避免敏捷爱好者通常庆祝的“快速失败”⽅法。没有什么⽐发布新版本的API(使先前版本中使⽤的端点或参数⽆效)更糟糕的了。API中的恒定版本控制可能会成为⽂档的噩梦。
在我与SwaggerHub(团队合作使⽤Swagger API规范的协作平台)的公司Smartbear进⾏的交谈中，他们说，现在团队⼿动编写规范⽽不是将源注释嵌⼊编程代码中以⾃动⽣成，现在更为普遍。规格。规范优先的⽅法有助于将⽂档⼯作分配给⽐⼯程师更多的团队成员。在编码之前定义规范还有助于团队开发出更好的API。
甚⾄在对API进⾏编码之前，您的规范就可以通过在规范中添加响应定义来⽣成模拟响应。模拟服务器
⽣成的响应看起来像是来⾃真实服务器的响应，但这只是代码中的预定义响应，对于⽤户⽽⾔似乎是动态的。
技术规范作者的⾓⾊
在我的⼤多数项⽬中，开发⼈员对Swagger或OpenAPI并不熟悉，因此我通常⼿动创建OpenAPI规范⽂档。此外，我通常⽆法访问编程源代码，并且我们的开发⼈员只会说英语作为第⼆或第三语⾔。他们不希望从事⽂档业务。
您很可能会发现您公司的⼯程师对Swagger或OpenAPI并不熟悉，但是有兴趣将其⽤作API⽂档的⼀种⽅法(基于架构的⽅法符合⼯程学的思维⽅式)。因此，您可能需要带头指导⼯程师，以获取必要的信息，⽅法和其他细节，以符合创建规范的最佳实践。
在这⽅⾯，技术作者在与API团队合作制定规范中可以发挥关键作⽤。如果您遵循规范优先的开发理念，那么这个领导⾓⾊可以帮助您在对API进⾏编码和锁定之前对其进⾏调整。这意味着您可能有机会影响端点的名称，⼀致性和模式，简单性以及API设计中通常要考虑的其他因素。
使⽤Swagger UI呈现您的OpenAPI规范
在拥有描述您的API的有效OpenAPI规范⽂档之后，您可以将该规范提供给其他⼯具以进⾏解析，并⽣
成类似于Petstore演⽰的交互式⽂档。
可能最常⽤的解析OpenAPI规范的⼯具是Swagger UI。(请记住，“ Swagger”是指API⼯具，⽽“ OpenAPI”是指与供应商⽆关的，与⼯具⽆关的规范。)下载Swagger UI后，很容易使⽤⾃⼰的规范⽂件对其进⾏配置。我将在接下来的部分中提供Swagger UI教程。
S wagger UI代码⽣成如下所⽰的显⽰：
Swagger Petstore演⽰展⽰了Swagger UI如何呈现OpenAPI规范
您还可以使⽤简单的天⽓API(作为课程⽰例)来查看Swagger UI⽰例集成。
⼀些设计师批评Swagger UI的可扩展/可折叠输出过时。同时，开发⼈员发现⼀页模型很有吸引⼒，并且喜欢放⼤或放⼤细节的功能。通过在⼀个视图中整合所有端点在同⼀页⾯上，⽤户可以⼀⽬了然地使⽤整个API。该显⽰使⽤户可以⼤致了解整体情况，这有助于降低复杂性并使其⼊门。在许多⽅⾯，Swagger UI显⽰是API的快速参考指南。
curl命令发送post请求带参数活动：通过Petstore演⽰探索Swagger UI
让我们通过Petstore演⽰获得Swagger UI的实际操作经验。Petstore演⽰提供了⼀个很好的⽰例，说明如何以可视⽅式呈现OpenAPI规范。
1. 转到Swagger宠物商店演⽰。 与⼤多数基于Swagger的输出⼀样，Swagger UI提供了“试⽤”按钮。要使其正常⼯作，您必须⾸先
通过单击“授权”并在“授权”模式中输⼊您的API密钥来授权Swagger。但是，Petstore授权模式仅⽤于演⽰⽬的。没有真正的代码授权这些请求，因此您可以关闭“授权”模式或完全跳过它。
2. 展开POST / pet端点。
POST / pet端点并在Swagger UI中尝试⼀下按钮
3. 点击试⽤。
单击“试⽤”后，“请求正⽂”字段中的⽰例值将变为可编辑的。
4. 在⽰例值中，将第⼀个id值更改为唯⼀的(并且不太可能重复)整数(例如24329)。将名称doggie更改为您可以记住的宠物名称(例如Bentley)。
5. 单击执⾏。

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。