Is there any annotation based Swagger Documentation creator available for Vert.x yet ? The rest end points are all managed using routers and as such if there is any way available to generate the Swagger documentation, that would be great.
I've gone through the Java Jersey based documentation creator using various annotations, but couldn't find anything for the Vert.x documentation. The official swagger wiki on Git Hub also doesn't house any document related to Vert.x documentations.
Since this question was asked Swagger has been named OpenAPI and Vert.x offers the Web API Contract module. Using this anupsaund created the vertx-auto-swagger repo (in turn based on vertx-openapi-spec-generator). It does:
Read Java Annotations and map them into a openAPI spec.
Serve the openAPI spec out on an end point.
Serve a distributable version of SwaggerUI which presents the swagger spec from point 2.
Which then allows annotations as follows:
#Operation(summary = "Find products by ID", method = "GET", operationId = "product/:productId",
tags = {
"Product"
},
parameters = {
#Parameter(in = ParameterIn.PATH, name = "productId",
required = true, description = "The unique ID belonging to the product", schema = #Schema(type = "string"))
},
responses = {
#ApiResponse(responseCode = "200", description = "OK",
content = #Content(
mediaType = "application/json",
encoding = #Encoding(contentType = "application/json"),
schema = #Schema(name = "product", example =
"{" +
"'_id':'abc'," +
"'title':'Red Truck'," +
"'image_url':'https://images.pexels.com/photos/1112597/pexels-photo-1112597.jpeg'," +
"'from_date':'2018-08-30'," +
"'to_date':'2019-08-30'," +
"'price':'125.00'," +
"'enabled':true" +
"}",
implementation = Product.class)
)
),
#ApiResponse(responseCode = "404", description = "Not found."),
#ApiResponse(responseCode = "500", description = "Internal Server Error.")
}
)
Related
In my project, All the endpoints are exposed by Spring Data Rest. I don't have the service and controller layer.
I have the required dependencies for Spring data rest and OpenApi support.
In the repository, CRUD methods are annotated as follows.
#Operation(summary = "Get Person based on Id passed as parameter")
#RestResource(exported = true)
#ApiResponses(value = { #ApiResponse(responseCode = "404", description = "Not Found"), #ApiResponse(responseCode = "500", description = "Internal Server Error") })
#ResponseStatus(value = HttpStatus.OK)
Optional<Person> findById(#Parameter(name="UUID") #RequestParam("UUID") #PathVariable Integer id);
In the Swagger UI, the description for the id, Operation Summary and any other props are not getting reflected.
Since I don't have RestControllers, is there a way to customize these things for endpoints exposed by the Spring data rest?
What I tried was
#ApiResponse(responseCode = "200", description = "Success", content = {#Content(mediaType = "application/json", schema = #Schema(implementation = ResponseEntity.class))})
but this is what I get under the response section in my apidoc. It seems like it's not reading the ResponseEntity class and not generating any schema.
Error-ModelName{namespace='org.springframework.http', name='ResponseEntity'}
and I am wondering if I can use openapi3 annotation to fix this.
Quarkus with microprofile openapi and swagger.
We are trying to create custom annotation for #APIResponses.
Is this possible in quarkus?
`org.eclipse.microprofile.openapi.annotations.APIResponses;`
`package org.eclipse.microprofile.openapi.annotations.*;`
`#Target({ElementType.METHOD, ElementType.TYPE, ElementType.ANNOTATION_TYPE})`
`#Inherited`
`#Documented`
`#Retention(RetentionPolicy.RUNTIME)`
`#Target(ElementType.TYPE)`
`#ApplicationScoped`
`#APIResponses(value = {`
`#APIResponse(responseCode = "200", description = ".."),`
`#APIResponse(responseCode = "201", description = "..") ,`
`#APIResponse(responseCode = "202", description = "..") }`
`)`
`public #interface customApiResponse {`
`}`
It is not a question of being possible in Quarkus but more possible with MicroProfile OpenAPI.
The ApiResponses annotation has a target defined to #Target({ ElementType.METHOD }) so you cannot use it on a type, only on methods.
Probably a good idea to raise the issue to the MicroProfile OpenAPI project explaining what you want to do and why and see if something should be changed. Then it will naturally end up in Quarkus.
I've got an apiKey in my swagger definition:
securityDefinition = #SecurityDefinition(
apiKeyAuthDefinitions = {#ApiKeyAuthDefinition(
key= "test",
in = ApiKeyAuthDefinition.ApiKeyLocation.HEADER,
name = "X-AUTH-TOKEN",
description = "LHT-AM API KEY"
)}
)
So SwaggerUI correctly offers authorization.
But how can i tell SwaggerUI to fill this authorization automatically from header?
I am able to create Project / task / attachment fine with Asana API with PHP.
Is there a way to create Bold for Emphasis description for task / project ?
I could not find that in Asana API.
Can someone point me to right direction?
I can confirm that if you send in html_notes instead of notes you will be able to use SOME html tags. The html tags that is valid is not documented, so you will have to test to find working tags.
"html_notes": "<strong>This will be bold in Asana</strong>"
I used the following with success when creating a task within a Workspace and a project. Note that this is using WebRequest in a ASP.NET WebApi (C#). But the Json string should work just fine with your project :)
IMPORTANT: Do not encode the html before POST.
ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls | SecurityProtocolType.Tls11 | SecurityProtocolType.Tls12;
var httpWebRequest = (HttpWebRequest)WebRequest.Create("https://app.asana.com/api/1.0/tasks");
httpWebRequest.Method = "POST";
httpWebRequest.PreAuthenticate = true;
httpWebRequest.Headers.Add("Authorization", "Bearer <PERSONAL_TOKEN>");
httpWebRequest.ContentType = "application/json";
string json = "{\"data\": {\"workspace\": \"123456789\",\"html_notes\": \"<strong>" + question.Message + "</strong>\",\"name\": \"" + Username + "\",\"projects\": \"123456789\"}}";
using (StreamWriter sw = new StreamWriter(httpWebRequest.GetRequestStream()))
{
sw.Write(json);
}
var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
result = streamReader.ReadToEnd();
}
A simple way using ASANA API's use this..
URL : https://app.asana.com/api/1.0/tasks
Method : POST
HEADER : Authorization:Bearer <your token>
Content-Type:application/json
Accept:application/json
Body :
{
"data": {
"approval_status": "pending",
"assignee": "1111----572318",
"assignee_status": "upcoming",
"due_on": "2019-09-15",
"followers": [
"31441----023","1617----554125"
],
"html_notes": "<body>Looking how can i create task under a <strong>project</strong></body>",
"name": "Task created form Postman - 3",
"workspace": "11288-----8660",
"projects":["1185----23561"]
}
}
Sample