wie man swagger apis in den Briefträger exportiert
Vor kurzem habe ich beruhigende Apis mit SpringMvc und swagger-ui (v2) geschrieben. Heute habe ich gerade den Button Import über dem Briefträger bemerkt Ich sah gerade den Kommentar "Importiere eine Postman Collection-, Environment-, Data Dump-, Curl-Anweisung oder eine RAML/WADL/Swagger (v1/v2)/Runscope-Datei." 
Zuerst hatte ich mich bemüht, aber keine Antworten befriedigten meine Situation.
Meine Frage ist also, wie man die Datei erstellt, die der Postbote benötigt.. Übrigens, Swagger kenne ich nicht.
Ich arbeite an PHP und habe Swagger 2.0 zur Dokumentation der APIs verwendet. Das Swagger-Dokument wird "on the fly" erstellt (zumindest verwende ich dies in PHP). Das Dokument wird im JSON-Format generiert.
Beispieldokument
{
"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": "[email protected]"
},
"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": {
}
}
Dies kann wie folgt in Postman importiert werden.
- Klicken Sie auf die Schaltfläche "Import" in der oberen linken Ecke der Postman-Benutzeroberfläche.
- Es werden mehrere Optionen zum Importieren des API-Dokuments angezeigt. Klicken Sie auf "Rohtext einfügen".
- Fügen Sie das JSON-Format in den Textbereich ein und klicken Sie auf Importieren.
- Sie sehen alle Ihre APIs als 'Postman Collection' und können diese vom Postman verwenden.
Sie können auch 'Import From Link' verwenden. Fügen Sie hier die URL ein, die das JSON-Format der APIs vom Swagger oder einem anderen API-Dokumententool generiert.
Dies ist meine JSON-Generierungsdatei (Document). Es ist in PHP. Ich habe keine Ahnung von Java zusammen mit Swagger.
<?php
require("vendor/autoload.php");
$swagger = \Swagger\scan('path_of_the_directory_to_scan');
header('Content-Type: application/json');
echo $swagger;
Die akzeptierte Antwort ist korrekt, aber ich werde vollständige Schritte für Java umschreiben.
Ich verwende derzeit Swagger V2 mit Spring Boot 2 und es ist ein einfacher 3-Schritt-Prozess.
Schritt 1: Fügen Sie die erforderlichen Abhängigkeiten in der pom.xml-Datei hinzu. Die zweite Abhängigkeit ist optional. Verwenden Sie sie nur, wenn Sie Swagger UI benötigen.
<!-- 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>
Schritt 2: Konfigurationsklasse hinzufügen
@Configuration
@EnableSwagger2
public class SwaggerConfig {
public static final Contact DEFAULT_CONTACT = new Contact("Usama Amjad", "https://stackoverflow.com/users/4704510/usamaamjad", "[email protected]");
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);
}
}
Schritt 3: Setup abgeschlossen und jetzt müssen Sie APIs in controllers dokumentieren
@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
}
Verwendungszweck:
Sie können über http://localhost:8080/v2/api-docs auf Ihre Dokumentation zugreifen. Kopieren Sie sie einfach und fügen Sie sie in Postman ein, um die Sammlung zu importieren.
Optionale Swagger-Benutzeroberfläche: Sie können Standalone-Benutzeroberfläche auch über http://localhost:8080/swagger-ui.html ohne jeden anderen Rest-Client verwenden.
- Klicken Sie auf die orangefarbene Schaltfläche ("Dateien auswählen").
- Navigieren Sie zum Swagger-Dokument (swagger.yaml).
- Nach Auswahl der Datei wird in POSTMAN eine neue Sammlung erstellt. Es enthält Ordner, die auf Ihren Endpunkten basieren.
Sie können auch einige Swagger-Beispieldateien online abrufen, um dies zu überprüfen (wenn Sie Fehler in Ihrem Swagger-Dokument haben).