I created a custom validation annotation which is similar to #javax.validation.constraints.Pattern. For #Pattern, swagger generates a nice schema like this:
summary: my summary
operationId: my_operation_id
parameters:
- name: myParam
in: header
required: true
schema:
maxLength: 30
pattern: ^\w+$ <--- THIS ONE
type: string
But for my annotation #CustomPattern (let's say), it doesn't! The generated swagger.yml does not have pattern key under schema. How can I create one?
This is in Micronaut.
I needed to have swagger.yml generated for my controller methods' parameters.
Just stick in a #io.swagger.v3.oas.annotations.media.Schema annotation with pattern attribute. Or if it's a List, then you could use #io.swagger.v3.oas.annotations.media.ArraySchema(schema = #Schema(pattern = ?))
That will do.
Related
Let's assume I have this definition in my openapi.yml (this is just a madeup example to depict the issue I have):
components:
schemas:
Address:
type: object
properties:
name:
type: string
zip:
type: integer
format: int64
town:
type: string
This will lead to the generation of code for the model that looks like this:
public class Address {
#JsonProperty("name")
private String name = null;
#JsonProperty("zip")
private Long zip = null;
#JsonProperty("town")
private String town = null;
...
My issue is that I have to persist this Pojo in a database and there exists no table Address (let's assume it is called Places instead) and the column for the zipcode is called zipcode instead of zip.
So I would need two things:
a way to tell OpenAPI about the aliases Address=Places and zip=zipcode.
a way to make this information change the code created. For Hibernate for example this would mean to add #Table(name="Places") and #Column(name="zipcode") in the right places.
Important remark: I can not change the API, it is expected to stick to Address and zip.
Can this be done ? I checked the specs and both swagger-codegen and openapi-generator (I'ld prefer the latter) but found no sign that something like this is covered.
For openapi-generator I had a look at the Mustache templates and as far as I can tell there is no code that refers any "alias information" that was defined in the yaml file.
Do I have to go the hard way and define an OpenAPI extension like this or this plus customize the templates all by myself ?
The closest I could find is this existing extension, that defines one type of alias. But this satisfies only the first part of my demand.
Use $ref
components:
schemas:
Address:
type: object
properties:
name:
type: string
zip:
type: integer
format: int64
town:
type: string
Places:
$ref: '#/components/schemas/Address'
I'd like to outline a multipart form request body, with some fields which are required, and other fields which are optional. Generally, in OAS Schema Objects, all properties not explicitly marked with required: true are defaulted to optional. However, when outlining a requestBody with multipart/form-data content, this seems to go by the wayside, and all fields are required.
I have tried multiple ways of designating the fields required vs optional. I receive compilation errors when trying to explicitly designate a field as optional with required: false.
OAS3 spec:
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- foo
properties:
foo:
type: string
format: binary
bar:
type: string
format: binary
Expected: Detail a multipart/form-data requestBody with some fields required and some optional.
In the code example above, foo should be a required file, while bar should be an optional file.
You can add an array of required fields, for example, if you'd like do make just foo required, should be like that:
requestBody:
content:
multipart/form-data:
schema:
type: object
required: [foo]
properties:
foo:
type: string
format: binary
bar:
type: string
format: binary
If you'd like to add more than one, just add the name on the array, such as [foo,bar].
When opening an API specification in Microsoft Azure API management we are giving some name and the swagger specification file also has some name as title. The name which we have given coming as API id and the title available in the Swagger.json is coming as API display name. So what is the difference between API id and API name in Azure API management?
It's common to all Azure resources to have name and id. Resource id is full "resource path" that goes like "/subscriptions/.../resourceGroups/.../providers/...". Last segment of that path is resource name.
Name is fixed field of the Contact Object in OpenAPI.
Name reflects the identifying name of the contact person/organization.
There's no id field in Contact object or any other openapi description fields, but openapi file may have user made id parameter.
Please, see this example:
parameters:
- name: id
in: path
description: ID of pet to use
required: true
schema:
type: array
style: simple
items:
type: string
Take a look at operationId. operationId is an optional unique string used to identify an operation. If provided, these IDs must be unique among all operations described in your API.
I have these fields marked as required in my yaml file (swagger spec)
MyType:
type: object
required:
- name
- amount
I am using swagger codegen maven plugin with these configurations:
<artifactId>swagger-codegen-maven-plugin</artifactId>
<version>2.2.3</version>
<language>spring</language>
<library>spring-mvc</library>
I would like to have required fields in spec to be made required in the generated classes as well. But that is not happening currently.
Are there configuration options to do that? I have <useBeanValidation>true</useBeanValidation> but this does not seem to work for me.
I saw a similar request enforcement of "required" fields in Definitions on Swagger-codegen GitHub page where suggestion was to use useBeanValidation and I do have it but it still does not work.
Created this request on Swagger-codegen GitHub page: Swagger-codegen enforcement of “required” fields in generated model classes
Found the solution. It was actually my mistake; I was expecting the field in the generated class to be marked required. It is rather the getter method which is annotated with #NonNull and required = true which solves the purpose. And now with the validation in place, I am able to see the validation is triggered and showing the message Amount should be present when amount is not passed in the request payload.
#ApiModelProperty(required = true, value = "Amount should be present")
#NotNull
public Amount getAmount() {
return amount;
}
I went to this swagger editor and looked into their example.
I wanted to try extending a model.
In the example there, they have:
Tag:
type: "object"
properties:
id:
type: "integer"
format: "int64"
name:
type: "string"
xml:
name: "Tag"
So I added my Tag2:
Tag2:
allOf:
- $ref: '#/definitions/Tag'
- properties:
prop:
type: "string"
My new model does appear in the Models List, but instead of having the 2 schema names (Tag and Tag2), I have two Tag entries. One of them correctly has the new 'prop' field.
How can I make the second one to appear with the correct name?
This is a bug in Swagger Editor. It's being tracked in:
https://github.com/swagger-api/swagger-editor/issues/1288
and is caused by
https://github.com/swagger-api/swagger-js/issues/1024