It depends on what kind of parameters they are. The examples below are in YAML (for readability), but you can use http://www.json2yaml.com to convert them to JSON. Security-related parameters: Authorization header, API keys, etc. Parameters used for authentication and authorization, such as the Authorization header, API key, pair of API keys, etc. should be defined … Read more
I wrote a quick tool to do this recently. I call it openapi-merge. There is a library and an associated CLI tool: https://www.npmjs.com/package/openapi-merge https://www.npmjs.com/package/openapi-merge-cli In order to use the CLI tool you just write a configuration file and then run npx openapi-merge-cli. The configuration file is fairly simple and would look something like this: { … Read more
Maybe this can help: swagger: ‘2.0’ info: version: 1.0.0 title: Bearer auth example description: > An example for how to use Bearer Auth with OpenAPI / Swagger 2.0. host: basic-auth-server.herokuapp.com schemes: – http – https securityDefinitions: Bearer: type: apiKey name: Authorization in: header description: >- Enter the token with the `Bearer: ` prefix, e.g. “Bearer … Read more
In OpenAPI 3.0, header parameters are defined in the same way as in OpenAPI 2.0, except the type has been replaced with schema: paths: /post: post: parameters: – in: header name: X-username schema: type: string When in doubt, check out the Describing Parameters guide. But in Swagger 3.0.0 parameters are replaced by request bodies. This … Read more
In your example, you can use a single model for both GET and POST/PUT, with properties only used in the GET response marked as readOnly. From the spec: readOnly Declares the property as “read only”. This means that it MAY be sent as part of a response but MUST NOT be sent as part of … Read more
It seems Swashbuckle doesn’t implement polymorphism correctly and I understand the point of view of the author about subclasses as parameters (if an action expects an Animal class and behaves differently if you call it with a dog object or a cat object, then you should have 2 different actions…) but as return types I … Read more
OpenAPI 3.1 Define the property as anyOf of the $ref and type: ‘null’. YAML version: foo: anyOf: – type: ‘null’ # Note the quotes around ‘null’ – $ref: ‘#/components/schemas/Foo’ JSON version: “foo”: { “anyOf”: [ { “type”: “null” }, { “$ref”: “#/components/schemas/Foo” } ] } Why use anyOf and not oneOf? oneOf will fail validation … Read more
Swagger Editor Paste your OpenAPI 2.0 definition into https://editor.swagger.io and select Edit > Convert to OpenAPI 3 from the menu. Swagger Converter Converts OpenAPI 2.0 and Swagger 1.x definitions to OpenAPI 3.0. https://converter.swagger.io/api/convert?url=OAS2_YAML_OR_JSON_URL This gives you JSON. If you want YAML, send the request with the Accept: application/yaml header: curl “https://converter.swagger.io/api/convert?url=OAS2_YAML_OR_JSON_URL” -H “Accept: application/yaml” -o … Read more
I prefer to use bean initialization instead of annotation. import io.swagger.v3.oas.models.Components; import io.swagger.v3.oas.models.OpenAPI; import io.swagger.v3.oas.models.info.Info; import io.swagger.v3.oas.models.security.SecurityRequirement; import io.swagger.v3.oas.models.security.SecurityScheme; import org.springframework.beans.factory.annotation.Value; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.util.StringUtils; @Configuration public class OpenApi30Config { private final String moduleName; private final String apiVersion; public OpenApi30Config( @Value(“${module-name}”) String moduleName, @Value(“${api-version}”) String apiVersion) { this.moduleName = moduleName; this.apiVersion = apiVersion; … Read more
GraphQL APIs are usually documented through the documentation facilities provided by the GraphQL server itself: The type system and the descriptions on the types and fields. A tool like GraphQL playground lets you explore the API documentation through clicking/searching in a visual document tree or through IDE like features (autocomplete + tooltips). This is mostly … Read more