I am working on a Java application. With io.swagger.v3, we can list all acceptable values of the parameter by using #Parameter(description = "Level of detail in result", schema = #io.swagger.v3.oas.annotations.media.Schema(allowableValues = {"low", "high", "debug" })) so that only "low", "high", "debug" are allowed. Now I was asked to use org.eclipse.microprofile.openapi instead of swagger. However, I cannot find how to achieve this with oepnapi. Could someone help me plz?
Related
I have a problem with a REST API endpoint in FastAPI that accepts a list of strings via a single query parameter. An example of this endpoint's usage is:
http://127.0.0.1:8000/items/2?short=false&response=this&response=that
Here, the parameter named 'response' accepts a list of strings as documented in FastAPI tutorial, section on Query Parameters and String Validation. The endpoint works as expected in the browser.
However, it does not work in Swagger docs. The button labeled 'Add string item' shakes upon clicking 'Execute' to test the endpoint. Swagger UI seems unable to create the expected URL with the embedded query parameters (as shown in Fig 1.).
The code for the endpoint is as follows. I have tried with and without validation.
#app.get("/items/{item_ID}")
async def getQuestion_byID(item_ID: int = Path(
...,
title = "Numeric ID of the question",
description = "Specify a number between 1 and 999",
ge = 1,
le = 999
), response: Optional[List[str]] = Query(
[],
title="Furnish an answer",
description="Answer can only have letters of the alphabet and is case-insensitive",
min_length=3,
max_length=99,
regex="^[a-zA-Z]+$"
), short: bool = Query(
False,
title="Set flag for short result",
description="Acceptable values are 1, True, true, on, yes"
)):
"""
Returns the quiz question or the result.
Accepts item ID as path parameter and
optionally response as query parameter.
Returns result when the response is passed with the item ID.
Otherwise, returns the quiz question.
"""
item = question_bank.get(item_ID, None)
if not item:
return {"question": None}
if response:
return evaluate_response(item_ID, response, short)
else:
return {"question": item["question"]}
Grateful for any help.
As described here, this happens due to that OpenAPI applies the pattern (as well as minimum and maximum constraints) to the schema of the array itself, not just the individual items in the array. If you checked the OpenAPI schema at http://127.0.0.1:8000/openapi.json, you would see that the schema for the response parameter appears as shown below (i.e., validations are being applied to the array itself as well):
{
"description": "Answer can only have letters of the alphabet and is case-insensitive",
"required": false,
"schema": {
"title": "Furnish an answer",
"maxLength": 99,
"minLength": 3,
"pattern": "^[a-zA-Z]+$",
"type": "array",
"items": {
"maxLength": 99,
"minLength": 3,
"pattern": "^[a-zA-Z]+$",
"type": "string"
},
"description": "Answer can only have letters of the alphabet and is case-insensitive",
"default": []
},
"name": "response",
"in": "query"
}
Solution 1
As mentioned here, you could use a Pydantic constr instead to specify items with that contraint:
my_constr = constr(regex="^[a-zA-Z]+$", min_length=3, max_length=99)
response: Optional[List[my_constr]] = Query([], title="Furnish an...", description="Answer can...")
Solution 2
Keep your response parameter as is. Copy the OpenAPI schema from http://127.0.0.1:8000/openapi.json, remove the pattern (as well as minimum and maximum attributes) from response's (array) schema and save the OpenAPI schema to a new file (e.g., my_openapi.json). It should look like this:
...
{
"description": "Answer can only have letters of the alphabet and is case-insensitive",
"required": false,
"schema": {
"title": "Furnish an answer",
"type": "array",
"items": {
"maxLength": 99,
"minLength": 3,
"pattern": "^[a-zA-Z]+$",
"type": "string"
},
"description": "Answer can only have letters of the alphabet and is case-insensitive",
"default": []
},
"name": "response",
"in": "query"
},
...
Then, in your app, instruct FastAPI to use that schema instead:
import json
app.openapi_schema = json.load(open("my_openapi.json"))
Solution 3
Since the above solution would require you to copy and edit the schema every time you make a change or add new endpoints/parameters, you would rather modify the OpenAPI schema as described here. This would save you from copying/editing the schema file. Make sure to add the below at the end of your code (after defining all the routes).
from fastapi.openapi.utils import get_openapi
def custom_openapi():
if app.openapi_schema:
return app.openapi_schema
openapi_schema = get_openapi(
title="FastAPI",
version="0.1.0",
description="This is a very custom OpenAPI schema",
routes=app.routes,
)
del openapi_schema["paths"]["/items/{item_ID}"]["get"]["parameters"][1]["schema"]["maxLength"]
del openapi_schema["paths"]["/items/{item_ID}"]["get"]["parameters"][1]["schema"]["minLength"]
del openapi_schema["paths"]["/items/{item_ID}"]["get"]["parameters"][1]["schema"]["pattern"]
app.openapi_schema = openapi_schema
return app.openapi_schema
app.openapi = custom_openapi
In all the above solutions, the constraints annotation that would normally be shown in OpenAPI under response (i.e., (query) maxLength: 99 minLength: 3 pattern: ^[a-zA-Z]+$), won't appear (since Swagger would create that annotation from the constraints applied to the array, not the items), but there doesn't seem to be a way to preserve that. In Solutions 2 and 3, however, you could modify the "in" attribute, shown in the JSON code snippet above, to manually ddd the annotation. But, as HTML elements, etc., are controlled by Swagger, the whole annotation would appear inside parentheses and without line breaks between the constraints. Nevertheless, you could still inform users about the constraints applied to items, by specifying them in the description of your Query parameter.
I'm implementing a search for a user's joined Teams unsing Microsoft Graph. The idea is to make a call to /beta/me/joinedTeams and use a ?$filter=startswith(description,'searchterm') filter.
So for example when I try the request https://graph.microsoft.com/beta/me/joinedTeams?$filter=startswith(description,'Business') in the Microsoft Graph Explorer it ignores the filter and I get these results:
{
"#odata.context": "https://graph.microsoft.com/beta/$metadata#groups",
"value": [
{
"id": "02bd9fd6-8f93-4758-87c3-1fb73740a315",
"displayName": "HR Taskforce",
"description": "Welcome to the HR Taskforce team.",
"isArchived": false
},
{
"id": "13be6971-79db-4f33-9d41-b25589ca25af",
"displayName": "Business Development",
"description": "Welcome to the BizDev team.",
"isArchived": false
},
{
"id": "8090c93e-ba7c-433e-9f39-08c7ba07c0b3",
"displayName": "X1050 Launch Team",
"description": "Welcome to the team that we've assembled to launch our product.",
"isArchived": false
}
]
}
Am I doing something wrong with my request?
Your request is right, but the joinedTeams does not support filtering or ordering results. So although we pass the filter/orderby parameter, when Microsoft Graph sees a query parameter it doesn't expect, it simply ignores the unknown filter/orderby parameter and returns an unfiltered/default-sorted result.
I have tried the api with odata query parameters for trial O365 account and real account.
https://developer.microsoft.com/en-us/graph/docs/concepts/query_parameters
Not all parameters are supported across all Microsoft Graph APIs, and
support might differ significantly between the v1.0 and beta
endpoints.
The only suggestion for you is to vote up the existing feature request in User Voice or submit a new one.
Thanks for pointing this out. As Seiya points out, /me/joinedTeams does not support the OData query parameters. The documentation suggested otherwise, I've made a doc fix that should propagate in the next day or two.
I'm documenting a Rails app with Swagger 2.0 and using Swagger-UI as the human-readable documentation/sandbox solution.
I have a resource where clients can store arbitrary metadata to query later. According to the Rails convention, the query would be submitted like so:
/posts?metadata[thing1]=abc&metadata[thing2]=def
which Rails translates to params of:
{ "metadata" => { "thing1" => "abc", "thing2" => "def" } }
which can easily be used to generate the appropriate WHERE clause for the database.
Is there any support for something like this in Swagger? I want to ultimately have Swagger-UI give some way to modify the generated request to add on arbitrary params under the metadata namespace.
This doesn't appear supported yet (over 2 years after you asked the question), but there's an ongoing discussion & open ticket about adding support for this on the OpenAPI github repo. They refer to this type of nesting as deepObjects.
There's another open issue where an implementation was attempted here. Using the most recent stable swagger-ui release, however, I have observed it working as I expect:
"parameters": [
{
"name": "page[number]",
"in": "query",
"type": "integer",
"default": 1,
"required": false
},
{
"name": "page[size]",
"in": "query",
"type": "integer",
"default": 25,
"required": false
}
This presents the expected dialog box & works with Try it out against a working server.
I don't believe there is a good way to specify arbitrary or a selection of values (e.g. an enum), so you may have to add parameters for every nesting option.
I am trying to access an url similar to http://example.com/service1?q1=a&q2=b. However q1 will not have any values associated with it sometimes but is required to access the service (http://example.com/service1?q1=&q2=b). How do I achieve this through swagger ui JSON. I've tried using allowEmptyValue option but it doesn't seem to work.
Please find below the sample JSON I tried using allowEmptyValue option,
{
"path": "/service1.do",
"operations": [{
"method": "GET",
"type": "void",
"parameters": [{
"name": "q1",
"in" : "query",
"required": false,
"type": "string",
"paramType": "query",
"allowEmptyValue": true
},{
"name": "q2",
"in" : "query",
"required": true,
"type": "string",
"paramType": "query",
}
],
"responseMessages": [{
"code": 200,
"responseModel": "/successResponseModel"
}
}
When an empty value is passed to q1, swagger frames the URL as http://example.com/service1?q2=b. Is there anyway to include q1 with empty values to be included in the URL (http://example.com/service1?q1=&q2=b) ?
Any help would be greatly appreciated.
It looks like your problem is a known issue of swagger-ui that hasn't fixed yet. see.
As a workaround you may do one of the followings.
Option 1: Specify a default value.
This option have nothing to do with swagger-ui. In your ws-implementation, You have to add a default value(in your case "") to use when 'q1' is not added. Any REST framework has this option.
As the ws-implementation perspectives, this should be there in your ws, unless you have another service to be triggered when 'q1' is not added. (which might not be a good design in most cases) And you can use this as a forever solution, not temporary.
Option 2: using enums (not a consistent solution)
As Explained in this. You can specify your query parameter 'q1' as follows for your swagger definition.
{
"in": "query",
"name": "q1",
"type": "boolean",
"required": false,
"enum" : [true],
"allowEmptyValue" : true
}
(1) "required" must be false.
(2) "allowEmptyValue" must be true.
(3) "enum" must have exactly one non-empty value.
(4) "type" must be "boolean". (or "string" with a special enum, say "INCLUDE")
I managed to solve this by setting:
"required": true,
"allowEmptyValue": true
In the Swagger-UI a checkbox will then be displayed where you can send the empty value. That worked for me. If that was checked and an empty query parameter was passed, the URL would look something like this: https://example.com?
I'm doing an integration for JIRA using REST API 6.2.6. One thing that I need to do is to get Issue Type Scheme and Workflow Scheme for a project.
What I tried:
Issue Type Scheme
The only thing that I can get right now is a list of issue types using /rest/api/2/project/{projectIdOrKey}. I can't see any way of getting an ID of Issue Type Scheme. Looking at API there is no any endpoints for issue type schemes, so I guess it's not possible.
Workflow Scheme
/rest/api/2/project/{projectIdOrKey} doesn't return any information about Workflow Scheme. But there is an endpoint /rest/api/2/workflowscheme/{id}, so that means that it's possible to get ID somehow... At the end I want to get a list of workflows for a project to check transitions for an issue type.
Question
Is there any way to get the data I want? Maybe there is some hidden not documented API?
Note: I'm using only JIRA REST API.
This is what you want.
/rest/projectconfig/1/workflowscheme/{projectIdOrKey}
Latest Jira documentation provides information about the APIs which can be used to fetch details for issuetype scheme and workflow scheme. Below are the APIs which can be used for the same,
Fetching Issue type Scheme for a project Issuetype Scheme API
Rest URL:GET https://your-domain.atlassian.com/rest/api/2/issuetypescheme/project?projectId={projectId}'
Sample Response:
{
"maxResults": 100,
"startAt": 0,
"total": 3,
"isLast": true,
"values": [
{
"issueTypeScheme": {
"id": "10000",
"name": "Default Issue Type Scheme",
"description": "Default issue type scheme is the list of global issue types. All newly created issue types will automatically be added to this scheme.",
"defaultIssueTypeId": "10003",
"isDefault": true
},
"projectIds": [
"10000",
"10001"
]
}
]
}
Fetching workflow scheme configured for a project Workflow Scheme API
REST URl: GET https://your-domain.atlassian.com/rest/api/2/workflowscheme/{id}
Sample Response:
{
"id": 101010,
"name": "Example workflow scheme",
"description": "The description of the example workflow scheme.",
"defaultWorkflow": "jira",
"issueTypeMappings": {
"10000": "scrum workflow",
"10001": "builds workflow"
},
"draft": false,
"self": "https://your-domain.atlassian.net/rest/api/2/workflowscheme/101010"
}
As far as I am aware you can get the correct XML or JSON response from the
REST API:
/rest/api/2/project/{projectIdOrKey}.
Then if you want to find out the information about the workflowscheme you can do this programmatically by using the following information.
If you have an issue that you want to use then you can use it to get the workflowscheme id by doing this this:
ComponentAccessor.getWorkflowSchemeManager().getWorkflowScheme(issue.getProject()).get("id");
Then once you get the id of the workflow scheme e.g. 10, you then can get the scheme generic value as follows:
GernericValue scheme = ComponentAccessor.getWorkflowSchemeManager().getScheme(10);
Now that you have the scheme you then can get all of the workflows that are referenced in the scheme by doing this:
Collection<JiraWorkflow> workflows = ComponentAccessor.getWorkflowManager().getWorkflowsFromScheme(scheme);
Then if you want to get one workflow you will have to use:
workflows.iterator().next():
Also note, that workflows are identified by their name in JIRA as there are no id's in JiraWorkflow.
So that would be the approach I would use if I wanted to find out the workflowscheme information so I could use the id to then use the REST API:
But the main reason that you might not be able to find a workflowscheme is because it is not present in the JIRA's Issue.
Using this HTTP and inputting it into "Postman" as a get request will return all the JSON information.
Using this https://jira.atlassian.com/browse/JRA-25121/project/23 will return all the information for that project. Then using this REST API:
/rest/api/2/workflowscheme/{id}
Using this HTTP get request https://jira.atlassian.com/browse/JRA-25121/workflow/45 will get you the returned XML or JSON workflow information too.