Static Enum definitions on the Swagger Specs
Hi, I need the way how the static core / client specific enum values supported on the dynamic configurations can be exposed my api specs for dynamic configurations. In other words some enums will be defined on core while in some cases, the enums will be defined as part of client implementations. For example I have values for enum SRB, CRO, ALB, but client maybe want to add. his own. How that can be achieved and exposed through API spec? And do you ned something more of the context?
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}`); });
Retrieve model properties in operation layer
Hi guys, I'm relatively new to the OpenAPI Generator, and I'm eager to create a customized generator that can generate a web page featuring operation forms. My goal is to have each form dynamically populated with fields based on the properties of the operation model. While working in the operation layer, I've successfully retrieved the body parameter for a given operation. However, I'm currently facing a challenge in obtaining the properties of this body parameter's datatype. For instance, let's take the "createUser" endpoint, where the body parameter is of type "User" with properties like userId and userName. I'm curious if there's a general method or approach to retrieve these model properties directly within the operation layer (using {{#operations}} {{/operations}}). Specifically, I'm looking for a way to obtain the field names (e.g., userId and userName) along with their corresponding datatypes. Any guidance on this matter would be greatly appreciated!
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.
Java client code generated from anyOf using array and object types is not usable
Hi, I generated a Java client using https://editor-next.swagger.io/ for a REST API that we want to consume. The schemas for this API have various elements with a definition like this: ... "components": { ... "schemas": { "report": { "type": "object", "additionalProperties": false, "properties": { ... "analysis": { "anyOf": [ { "$ref": "#/components/schemas/analysisType" }, { "type": "array", "items": { "$ref": "#/components/schemas/analysisType" }, "description": "maximum 4" } ] } } }, "analysisType": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string" }, "codeDescription": { "type": "string" }, "percentage": { "type": "integer" }, "sequenceNumber": { "type": "integer" } }, "required": [ "code", "percentage", "sequenceNumber" ] } ... So it's basically a field that consists of either a single element of type AnalysisType, or an array of type AnalysisType. The Java code generated for this is useless. An interface named AnyOfanalysis is generated without any methods, and a class named AnalysisType implementing this interface is generated which is basically the single element case. A class named Report is also generated which has a field analysis of type AnyOfanalysis. Any ideas on this? Should I report this as an issue? P.S. Jackson can deal with this by configuring the ObjectMapper: test public void givenJsonElement_whenDeserializingAsList_thenCorrect() throws JsonParseException, JsonMappingException, IOException { ObjectMapper mapper = new ObjectMapper(); mapper.enable(DeserializationFeature.ACCEPT_SINGLE_VALUE_AS_ARRAY); String jsonElement = mapper.writeValueAsString(new AnalysisType().code("foo").percentage(20).sequenceNumber(1)); List<AnalysisType> asList = mapper.readValue(jsonElement, new TypeReference<List<AnalysisType>>() { }); assertEquals(1, asList.size()); assertEquals(AnalysisType.class, asList.get(0).getClass()); } If the generated code defines the field analysis of the class Report as List<AnalysisType> this would work out of the box.
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.
python flask swagger
""" this is cancel task --- tags: - task/{task_id}/cancel summary: 取消/终止任务 description: 取消/终止任务，当任务是queued是取消任务，当任务是started则是终止任务 components: securitySchemas: JWTAuth: type: http scheme: bearer security: - BearerAuth: [] parameters: - in: path name: task_id schema: oneOf: - type: integer - type: string format: uuid required: true description: integer or uuid type responses: 200: description: cancel success content: application/json: schema: $ref: '#/components/schemas/RespSchemaSuccess' type: object 400: description: cancel failure content: application/json: schema: $ref: '#/components/schemas/RespSchemaFailure' """ this is my code,but i can't authenticate by bear token,in docs that don't have a place to input bear token,how can i change this code
Generating OAS from Code
Hello, I am new to Swagger and exploring it to find a tool that can help me convert Python code to OAS (OpenAPI Specification). The codes have RESTful APIs, code, routes and is in Python. If the output is a YAML/JSON file with OAS that can be rendered by another tool, it will be awesome.Unique Operation IDs for APIs using JAX-RS sub-resources
TL;DR - is there any way to have more control over the 'operationId' given to operations in an OAS, when those APIs are implemented using JAX-RS's "subresource" feature. ---- I work on an open source Java project called Apache Solr that is trying to generate an OAS out of some existing JAX-RS and Swagger annotations. In Solr we have certain chunks of functionality that we offer from two slightly different paths, e.g. GET /collections/{name}/schema and GET /cores/{name}/schema. We represent this succinctly using JAX-RS "sub-resources", as in the snippet below: @Path("/collections/{name}/schema") public interface GetCollectionSchemaApi { @Path("/") GetSchemaApi get(); } @Path("/cores/{name}/schema") public interface GetCoreSchemaApi { @Path("/") GetSchemaApi get(); } public interface GetSchemaApi { @GET @Path("/name") @Operation(...) SchemaNameResponse getSchemaName(); // Definitions of other shared subpaths omitted here for brevity } 'swagger-gradle-plugin' reads these annotations and produces an OAS that is great in all respects, except that a numeric suffix is used to individuate the operationId of each of these similar APIs. e.g. "/collections/{name}/schema/name" : { "get": { "operationId": "getSchemaName", ... } }, "/cores/{name}/schema/name" : { "get": { "operationId": "getSchemaName_1", ... } } We use our OAS for code generation and these "_#" operationId suffixes are less than ideal in our generated code. Is there any way to influence how 'operationId's are picked and individuated for "@Operation" annotations in JAX-RS subresources. Or a way to work around these slightly wart-y operationIds when doing code generation?
