How to Integrate Swagger for jenkins REST API Documentation
Hello everyone, I'm a prospective GSoC participant with Jenkins and I'm exploring a project idea that involves integrating Swagger/OpenAPI for documenting the Jenkins REST API. Could anyone share insights on whether a full integration is feasible during GSoC, what potential challenges might arise, and any resources or documentation that might help? Project idea details: https://www.jenkins.io/projects/gsoc/2025/project-ideas/swagger-openapi-for-jenkins-rest-api/ Anyone's suggestion or guidance will means a lot to me, Thanks in advance for your guidance !!!
Avoid caching AnnotationIntrospector to support custom module loading. Issue: #4744
https://github.com/swagger-api/swagger-core/blob/24fca016b28d3f8363b29471312d3678a0f7a542/modules/swagger-core/src/main/java/io/swagger/v3/core/jackson/AbstractModelConverter.java#L46 Issue: Currently, binding the annotation introspector to _intr in `AbstractModelConverter.java` causes a divergence in functionality between Swagger's annotation introspector and Jackson's annotation introspector. This could lead to inconsistencies, especially when users extend Jackson with custom modules that perform custom annotation introspection. Solution: To address this, I propose that we avoid binding the introspector directly and instead retrieve the current annotation introspector from _mapper. This approach ensures that both Swagger and Jackson utilize the same introspector, maintaining functionality and consistency across the system. Use Case: This change is particularly beneficial for users implementing custom annotation introspection Github Issue Link: https://github.com/swagger-api/swagger-core/issues/4744 Github PR Link: https://github.com/swagger-api/swagger-core/pull/4728 Note: I hope this is the right forum to bring attention to the Github Issue and PR I created. I tried tagging maintainers in the PR, but failed to bring attention.
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}`); });
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); }
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?
