Swagger 2.0 to OpenApi 3.0
we are using all the classes with import io.swagger.annotations.*; and we have moved to jakarta. Please let me know where I can find the documentation to know what are annotations to be used. Please also suggest me swagger maven plugin which takes jakarta into consideration and generate a JSON file. Attach sample plugin to be used to generate JSON with open api 3 or greater.
Bugs with Annotations?
My Stack. Java 17/Jakarta EE10/Wildfly 21/ Swagger-core-jakarta 2.2.19. Using swagger-annotations. Bug 1. @Schema inside @Arrayschema. I am using @Arrayschema but i will also need to define the schema for the items and add some validations to it. If i use items= @Schema it gets worse, then the items class is not even generated.. Example: @JsonProperty("causes") @ArraySchema(maxItems = 4096, minItems = 0, schema = @Schema(implementation = String.class, description = "causes", pattern = "\\P{Cc}\\P{Cn}\\P{Cs}\\P{Cf}", minLength = 1, maxLength = 4096)) private List<String> causes; The only thing that makes is way to my OPENAPI.json file is that Items are of String.class. None of my validatons like min/max lenght, pattern etc is rendered. This creates a huge problem as my OWASP Top Ten static analyzer renders this a serious issue. Am i doing this wrong? Are there bugs?Do i need to add something? Bug 2. AdditionalProperties not set to false. I can not get the AdditionalProperties flag set. Ever Example @Schema(name = "CMSResponseError", description = "CMSResponseError", additionalProperties = Schema.AdditionalPropertiesValue.FALSE ) public class CMSResponseError implements CmsObject { This is again a red flag for my OWASP checks, as this poses a security threat. Am i doing this wrong? Are there bugs?Do i need to add something?
Use $ref in examples
I am building an update API in nest js and I want to document my API. In this update API I have different types of users and based on those users I have different properties (some properties are common across all type of users). I want to use those DTOs as an example for those different users. Can I do that? The examples code: export const updateDirectoryExample = Object.freeze({ sample_1: { summary: 'Contractor', // value: {}, $ref: '../dto/update-contractor.dto.ts', }, sample_2: { summary: 'Vendor', // value: {}, $ref: '../dto/update-vendor.dto.ts', }, }); Nest js controller code: @ApiOkResponse({ type: UpdateDirectoryResDto, }) @ApiBody({ type: UpdateDirectoryDto, examples: updateDirectoryExample, }) updateDirectory( @AuthUser() reqUserDetails: IRequestUserDetails, @Body() body: UpdateDirectoryDto, @Req() request: Request, ) { return this.directoryService.updateDirectory(reqUserDetails, body, request); }Regarding swagger is not working in nodejs as per the swagger document.
Hi there, I tried to setup swagger on nodejs as per the document par it is not working and present wrong data of swagger UI see the below attached screenshot. So just wanted to know how to setup swagger in nodejs so that all my apis display in one place. I tried lot of solutions on different different websites but same issue appeared. So kindly guide how to do that so that swagger is running properly. Reference site that I tried below: https://swagger.io/docs/open-source-tools/swagger-codegen/#:~:text=The%20Swagger%20Codegen%20is%20an,can%20be%20found%20in%20GitHub. https://levelup.gitconnected.com/how-to-add-swagger-ui-to-existing-node-js-and-express-js-project-2c8bad9364ce https://medium.com/bb-tutorials-and-thoughts/how-to-add-swagger-to-nodejs-rest-api-7a542cfdc5e1 https://plainenglish.io/blog/how-to-implement-and-use-swagger-in-nodejs-d0b95e765245 https://dev.to/kabartolo/how-to-document-an-express-api-with-swagger-ui-and-jsdoc-50do https://itnext.io/setting-up-swagger-in-a-node-js-application-d3c4d7aa56d4 https://github.com/Surnet/swagger-jsdoc/blob/master/README.md Looking forward to hearing from you. Thanks! Swagger.json: { "swagger": "2.0", "info": { "version": "1.0.0", "title": "My User Project CRUD", "description": "My User Project Application API", "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" } }, "host": "localhost:3000", "basePath": "/", "tags": [ { "name": "Users", "description": "API for users in the system" } ], "schemes": ["http"], "consumes": ["application/json"], "produces": ["application/json"] } Server.js: import swaggerUi from 'swagger-ui-express'; import swaggerDocument from './swagger.json'; app.use( '/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument) ); app.listen(port, () => { console.log(`Server running at ${process.env.SERVER_URL}`); });
Non-Primitive, Non-Scalar HTTP Values
How can standard HTTP values that are non-primitive, non-scalar be documented in OpenAPI? They most often occur in HTTP header fields, but they occasionally occur in the path or query string too. There appears to be no documentation or coverage for these scenarios. Are these a gap or omission from the specification? A few examples include: - Accept (with quality) (ex: Accept: application/json; q=0.8, application/xml, application/problem+json) - Range (ex: Range: bytes=0-99) -Content-Disposition (ex: Content-Disposition: attachment; filename=example.txt) -Link(ex: Link: <https://my.api.com/swagger.json>; rel="openapi" type="application/json") There are other cases as well. Some values in the OData protocol have specific value formats that seemingly cannot be described by OpenAPI. Arrays, for example, must be encoded with surrounding '[' and ']'. While an argument can be made that these values are objects and can be represented in the schema, there doesn't seem to be a way to control or define their serialization and deserialization. A well-known HTTP header cannot be represented in another format such as JSON nor are the values just text. A regular expression might be a way to enforce the format, but it is still a poor representation in the schema and UI. Perhaps I've missed something in the specifications or documentation. Any thoughts or suggestions are appreciated.
Specify both file content and body content in openapi
In my web application, when I create a form-data object that looks like the following: let fd = new FormData(); let data = {}; data.id = 5; // thing id, if this is an existing thing data.thingName = 'Resource Test'; // actual value from modal form data.thingType = 'Type Check'; // actual value from modal form data.relatedThingId = 19; // actual value from modal form, if bar selected fd.append('thing', JSON.stringify(data)); fd.append('file', values.file?.file); const upload = await axios.put('/things', fd); the 'thing' key along with it's corresponding stringified 'data' is loaded into request.body by axios, while the file object corresponding to the 'file' key is loaded into request.Files.file. I've found I can model the file portion of the request in my openapi document by doing the following (although I don't know if this is the correct way to do it: put: description: creates or updates a thing record requestBody: required: true content: multipart/form-data: schema: properties: file: type: object properties: name: description: the name of the file being stored type: number mimetype: description: the mimetype of the file type: string data: description: the body of the file type: string format: binary However, I'm having trouble figuring out (or finding examples/instructions) on how to model the part of the request that ends up in the request body. Trying to add a separate 'parameters' section where '- in: body' generates an error, saying that 'body' is not one of the 4 permitted 'in' values ("allowedValues: path, query, header, cookie"). Can anyone share how to model what I'm attempting?
Separate path/tag API definitions for external APi
Hello, I am currently using swagger-jaxrs2-servlet-initializer with mostly default configuration to generate one big OpenApi definition. Is there any way to configure swagger (via annotations, configuration?) to output multiple API definitions defined via path prefix or tag? Would need a separate file, that can be hosted independently for an external API for customer. Regards!Need help in generating swagger 3.0 specification
I have a JAVA project that is Swagger-annotated withSwagger Spec 2.0 annotations. I have been using swagger-maven-plugin to generate theSwagger specification (https://github.com/kongchen/swagger-maven-plugin). I want to upgrade to Swagger Spec 3.0. I will change the annotations manually in the project. But I need help how to generate the specification in 3.0. As the swagger-maven-plugin supports only upto 2.0. any help would be really appreciated.How to document HATEOAS in the OpenAPI specification
Hi Team, I have a REST API with aHATEOAS concept, may I know how can I document it in OpenAPI specifications? I tried in the following way[1] links directing to link schema under the component sections, paths: /items/{itemId}: get: responses: '200': description: Successful response content: application/json: schema: type: object properties: itemId: type: integer itemName: type: string links: type: array items: $ref: '#/components/schemas/Link' components: schemas: Link: type: object properties: rel: type: string href: type: string later I got to know about the Link section in the responsehttps://swagger.io/docs/specification/links/, May I know which approach is suitable for theHATEOAS mapping in REST API.
How import roles
Hi all, I'm working with Swagger open API 2.2.15 in Java through this configuration: @Bean public OpenAPI openAPI() { return new OpenAPI().components(new Components().addSecuritySchemes(OAUTH_SCHEME_NAME, createOAuthScheme())) .addSecurityItem(new SecurityRequirement().addList(OAUTH_SCHEME_NAME)) .info(new Info().title("Cities Generator").description("Web console").version("1.0")); } private SecurityScheme createOAuthScheme() { OAuthFlows flows = createOAuthFlows(); return new SecurityScheme().type(SecurityScheme.Type.OAUTH2).flows(flows); } private OAuthFlows createOAuthFlows() { OAuthFlow flow = createAuthorizationCodeFlow(); return new OAuthFlows().implicit(flow); } private OAuthFlow createAuthorizationCodeFlow() { return new OAuthFlow().authorizationUrl(authServerUrl + "/realms/" + realm + "/protocol/openid-connect/auth"); } I would understand how to import the roles in the subject. Actually, this configuration adds to my user an anonymous role ROLE_anonymous but I would the authorities imported from my external system. The login is ok
