【发布时间】：2016-12-28 13:45:09
【问题描述】：
最近我用 SpringMvc 和 swagger-ui(v2) 编写了 restful API。我注意到 Postman 中的 Import 功能：
所以我的问题是如何创建 Postman 需要的文件？
我不熟悉 Swagger。
【问题讨论】：
-
这真是太棒了……！！！
【发布时间】：2016-12-28 13:45:09
【问题描述】：
推荐你阅读这个答案
https://stackoverflow.com/a/51072071/4712855
参考https://stackoverflow.com/posts/39072519的回答，然后部分删除返回的内容。最后发现swagger缺少一些配置，postmat无法导入。
需要在swagger中添加如下配置
@Bean
public Docket api(SwaggerProperties swaggerProperties) {
swaggerProperties.setTitle("my-project");
swaggerProperties.setDescription("my project");
swaggerProperties.setVersion("v1");
swaggerProperties.getContact().setUrl("http");
//I overlooked other configurations. Note that my swagger configuration lacks these.
}
总之，ApiInfoBuilder类中的属性尽可能的赋值
spring-boot 版本：2.3.10.RELEASE springfox-swagger 版本：2.9.2
【讨论】：
你可以这样做：邮递员 -> 导入 -> 链接 -> {root_url}/v2/api-docs
【讨论】：
接受的答案是正确的，但我将重写 java 的完整步骤。
我目前正在使用 Swagger V2 和 Spring Boot 2，这是一个简单的 3 步过程。
第 1 步： 在 pom.xml 文件中添加所需的依赖项。第二个依赖项是可选的，仅当您需要 Swagger UI 时才使用它。
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
第二步：添加配置类
@Configuration
@EnableSwagger2
public class SwaggerConfig {
public static final Contact DEFAULT_CONTACT = new Contact("Usama Amjad", "https://stackoverflow.com/users/4704510/usamaamjad", "hello@email.com");
public static final ApiInfo DEFAULT_API_INFO = new ApiInfo("Article API", "Article API documentation sample", "1.0", "urn:tos",
DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList<VendorExtension>());
@Bean
public Docket api() {
Set<String> producesAndConsumes = new HashSet<>();
producesAndConsumes.add("application/json");
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(DEFAULT_API_INFO)
.produces(producesAndConsumes)
.consumes(producesAndConsumes);
}
}
第 3 步： 设置完成，现在您需要在 controllers 中记录 API
@ApiOperation(value = "Returns a list Articles for a given Author", response = Article.class, responseContainer = "List")
@ApiResponses(value = { @ApiResponse(code = 200, message = "Success"),
@ApiResponse(code = 404, message = "The resource you were trying to reach is not found") })
@GetMapping(path = "/articles/users/{userId}")
public List<Article> getArticlesByUser() {
// Do your code
}
用法：
您可以从 http://localhost:8080/v2/api-docs 访问您的文档，只需将其复制并粘贴到 Postman 中即可导入集合。
可选的 Swagger UI：您还可以通过 http://localhost:8080/swagger-ui.html 使用独立的 UI，无需任何其他 rest 客户端，这非常好，您可以轻松托管您的文档。
【讨论】：
-
导入时出错：导入 Swagger 2.0 时出错：(Patchable) parameter.type 对于非正文参数是必需的
我从事 PHP 工作，并使用 Swagger 2.0 来记录 API。 Swagger 文档是动态创建的（至少我在 PHP 中使用的是这种文档）。文档以 JSON 格式生成。
示例文档
{
"swagger": "2.0",
"info": {
"title": "Company Admin Panel",
"description": "Converting the Magento code into core PHP and RESTful APIs for increasing the performance of the website.",
"contact": {
"email": "jaydeep1012@gmail.com"
},
"version": "1.0.0"
},
"host": "localhost/cv_admin/api",
"schemes": [
"http"
],
"paths": {
"/getCustomerByEmail.php": {
"post": {
"summary": "List the details of customer by the email.",
"consumes": [
"string",
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "email",
"in": "body",
"description": "Customer email to ge the data",
"required": true,
"schema": {
"properties": {
"id": {
"properties": {
"abc": {
"properties": {
"inner_abc": {
"type": "number",
"default": 1,
"example": 123
}
},
"type": "object"
},
"xyz": {
"type": "string",
"default": "xyz default value",
"example": "xyz example value"
}
},
"type": "object"
}
}
}
}
],
"responses": {
"200": {
"description": "Details of the customer"
},
"400": {
"description": "Email required"
},
"404": {
"description": "Customer does not exist"
},
"default": {
"description": "an \"unexpected\" error"
}
}
}
},
"/getCustomerById.php": {
"get": {
"summary": "List the details of customer by the ID",
"parameters": [
{
"name": "id",
"in": "query",
"description": "Customer ID to get the data",
"required": true,
"type": "integer"
}
],
"responses": {
"200": {
"description": "Details of the customer"
},
"400": {
"description": "ID required"
},
"404": {
"description": "Customer does not exist"
},
"default": {
"description": "an \"unexpected\" error"
}
}
}
},
"/getShipmentById.php": {
"get": {
"summary": "List the details of shipment by the ID",
"parameters": [
{
"name": "id",
"in": "query",
"description": "Shipment ID to get the data",
"required": true,
"type": "integer"
}
],
"responses": {
"200": {
"description": "Details of the shipment"
},
"404": {
"description": "Shipment does not exist"
},
"400": {
"description": "ID required"
},
"default": {
"description": "an \"unexpected\" error"
}
}
}
}
},
"definitions": {
}
}
这可以按如下方式导入 Postman。
- 点击 Postman UI 左上角的“导入”按钮。
- 您将看到导入 API 文档的多个选项。点击“粘贴原始文本”。
- 将JSON格式粘贴到文本区，点击导入。
- 您将看到所有 API 为“Postman Collection”，并且可以从 Postman 中使用它。
您也可以使用“从链接导入”。在此处粘贴从 Swagger 或任何其他 API 文档工具生成 API 的 JSON 格式的 URL。
这是我的文档 (JSON) 生成文件。它在 PHP 中。我不知道 JAVA 和 Swagger。
<?php
require("vendor/autoload.php");
$swagger = \Swagger\scan('path_of_the_directory_to_scan');
header('Content-Type: application/json');
echo $swagger;
【讨论】：
-
谢谢，但现在的问题是如何从 swagger-ui 导出文件？而且链接没用。
-
@DemonColdmist 我已经添加了生成 API 的代码。基本上，它会扫描整个目录，检查注释并生成 JSON/YAML 输出。抱歉，我没有在 JAVA 中使用 Swagger。
-
谢谢，如果它可以用 PHP 导出，Java 也可以。我会把它翻译成Java。
-
在使用 springfox-swagger2 依赖项的 java 应用程序中，您可以通过打开浏览器并前往 localhost:8080/v2/api-docs 将 JSON 导入 Postman，如本答案中所述
-
@JDpawar 谢谢，导入成功，但它不会在邮递员中为任何 POST API 生成任何“正文”信息。有什么想法吗？
- 点击橙色按钮（“选择文件”）
- 浏览到 Swagger 文档 (swagger.yaml)
- 选择文件后，会在 POSTMAN 中创建一个新集合。它将包含基于您的端点的文件夹。
您还可以在线获取一些示例 swagger 文件来验证这一点（如果您的 swagger 文档中有错误）。
【讨论】：
-
你能告诉我如何导出swagger.yaml吗？我在SpringMvc中使用swagger-ui。
-
你想从哪里导出 swagger？你已经在使用 swagger 来编写你的 YAML 了吗？