Solución:
Trabajo en PHP y he usado Swagger 2.0 para documentar las API. El documento Swagger se crea sobre la marcha (al menos eso es lo que uso en PHP). El documento se genera en formato JSON.
Documento de muestra
"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":
Esto se puede importar a Postman de la siguiente manera.
- Clickea en el ‘Importar‘en la esquina superior izquierda de la interfaz de usuario de Postman.
- Verá varias opciones para importar el documento API. Clickea en el ‘Pegar texto sin procesar‘.
- Pegue el formato JSON en el área de texto y haga clic en importar.
- Verá todas sus API como ‘Colección cartero‘y puede usarlo del cartero.
También puede utilizar “Importar desde enlace”. Aquí pegue la URL que genera el formato JSON de las API desde Swagger o cualquier otra herramienta de documento API.
Este es mi archivo de generación de documentos (JSON). Está en PHP. No tengo idea de JAVA junto con Swagger.
Con .Net Core ahora es muy fácil:
- Ve y busca la URL JSON en tu página de swagger:
- Haga clic en ese enlace y copie la URL
- Ahora ve a Postman y haz clic en Importar:
- Seleccione lo que necesita y obtendrá una buena colección de puntos finales:
La respuesta aceptada es correcta, pero volveré a escribir los pasos completos para java.
Estoy usando actualmente Swagger V2 con Spring Boot 2 y es un proceso sencillo de 3 pasos.
Paso 1: Agregue las dependencias requeridas en pom.xml expediente. La segunda dependencia es opcional, úsela solo si necesita Swagger UI.
io.springfox
springfox-swagger2
2.9.2
io.springfox
springfox-swagger-ui
2.9.2
Paso 2: Agregar clase de configuración
@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());
@Bean
public Docket api()
Set producesAndConsumes = new HashSet<>();
producesAndConsumes.add("application/json");
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(DEFAULT_API_INFO)
.produces(producesAndConsumes)
.consumes(producesAndConsumes);
Paso 3: Configuración completa y ahora necesita documentar las API en controllers
@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 getArticlesByUser()
// Do your code
Uso:
Puede acceder a su documentación desde http://localhost:8080/v2/api-docs simplemente cópielo y péguelo en Postman para importar la colección.
Interfaz de usuario de Swagger opcional: También puede usar la interfaz de usuario independiente sin ningún otro cliente de descanso a través de http://localhost:8080/swagger-ui.html y es bastante bueno, puede alojar su documentación sin problemas.
Si tienes alguna desconfianza o forma de aclarar nuestro noticia puedes ejecutar una aclaración y con deseo lo estudiaremos.