How to generate OpenAPI 3 documentation from protobuf files
I searched for the answer recently and found this package: protobuf2swagger It can be run in CLI with a js config file required. This packaged solved my problem.
openapi
How to define enum mapping in OpenAPI?
OpenAPI 3.1 OpenAPI 3.1 uses the latest JSON Schema, and the recommended way to annotate individual enum values in JSON Schema is to use oneOf+const instead of enum. This way you can specify both custom names (title) and descriptions for enum values. Severity: type: integer oneOf: – title: HIGH const: 2 description: An urgent problem … Read more
Open API vs. REST API – difference
REST (REpresentational State Transfer) describes a way how a clients and servers interact with each other. REST communication typically bases on HTTP protocol (but that isn’t a requirement) and requests are made to a resource URI, possibly containing additional request data, and replies can be anything: HTML, XML, JSON, CSV, plain-text or even raw binary … Read more
How to generate OpenAPI 3.0 YAML file from existing Spring REST API?
We have used lately springdoc-openapi java library. It helps automating the generation of API documentation using spring boot projects. It automatically deploys swagger-ui to a spring-boot application Documentation will be available in HTML format, using the official [swagger-ui jars]: The Swagger UI page should then be available at http://server:port/context-path/swagger-ui.html and the OpenAPI description will be … Read more
Use java.time.Instant to represent DateTime instead of OffsetDateTime
just add to the configuration of openapi-generator-maven-plugin <typeMappings> <typeMapping>OffsetDateTime=Instant</typeMapping> </typeMappings> <importMappings> <importMapping>java.time.OffsetDateTime=java.time.Instant</importMapping> </importMappings>
Swagger schema properties ignored when using $ref – why?
TL;DR: $ref siblings are supported (to an extent) in OpenAPI 3.1. In previous OpenAPI versions, any keywords alongside $ref are ignored. OpenAPI 3.1 Your definition will work as expected when migrated to OpenAPI 3.1. This new version is fully compatible with JSON Schema 2020-12, which allows $ref siblings in schemas. openapi: 3.1.0 … components: schemas: … Read more
How to define header parameters in OpenAPI 3.0?
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
How to use ‘Authorization: Bearer ‘ in a Swagger Spec
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
OpenAPI 3.0 – how to define file download operation correctly
I believe content is what you’re looking for. You can also use contentReference to reference a reusable object in components. For example: paths: /files/{fileName}: get: summary: download file operationId: downloadFile description: this API is for file download parameters: – in: path name: fileName schema: type: string required: true description: The name of file to download … Read more
Swagger complex response model with dynamic key value hash maps
Your usage of additionalProperties is correct and your model is correct. additionalProperties In Swagger/OpenAPI, hashmap keys are assumed to be strings, so the key type is not defined explicitly. additionalProperties define the type of hashmap values. So, this schema type: object additionalProperties: type: string defines a string-to-string map such as: { “en”: “English text”, “de”: … Read more