It is not possible to create subgroups in the Swagger documentation.
Further, there is no possibility to sort the models (A, B).
For the operations, it is possible to work around it using tags.
Is there a similar solution for the Data Definitions?
(We are using Swashbuckle to create an HTML description.)
Related
I'm trying to create swagger documentation for an existing codebase which has a complex JSON request structure and a complex JSON response structure shared across multiple endpoints. I'd like for these structures to appear in the swagger UI, and I'd like to avoid repeating definitions (because the structure involves several hundred-plus item enums and is also recursive). For the same reason, I'd also like to avoid sticking everything in a single enormous yaml file and using the template hack.
Swagger 2.0 has a "definitions" section outside of the namespace of a particular endpoint for defining JSON fragments that can be used across endpoints, but it is unclear how to define that section using flasgger.
What is the best way to expose these complex structures through flasgger?
I wanted to try out the code first approach with an OpenAPI spec. For testign purposes I treied the Pet Store Example from SwaggerHub.
In the generated Code I noticed, that there is no logic involving routing.
I also noticed that the code in the service folder is not even used when I run the nodejs server (changing values of example data changes nothing in the output. The API seems to run a swaggerhub server.
Do I have a missunderstanding here, what the swagger code gen does?
On the other hand the client code generation looks how I woudl expect it. Instead of creating rest requests in my client I only have to execute methods of the services.
Based off your question, I would argue you're actually doing a "design-first" approach.
Code-first is when you have an existing codebase/service and you then create your documentation after (whether it is generated or hand written).
A design-first approach is when you create your documentation first, and THEN build out your code. If you have an OpenAPI document, and you're using Swagger codegen to create some code, then you're doing design-first.
As for your question involving routing, all Swagger codegen will do for you is generate some boilerplate code based off of your OpenAPI document. It will not add any business logic, or even route the API calls for you. It is then on you to implement all this logic after the fact.
I'm using Quarkus to build a project and I've decided to use Reactive Routes.
I'd like to add OpenAPI information and a Swagger UI to my project. It seems like that is possible using RestEasy but I didn't find information about the same with Reactive Routes.
Is that possible? I tried to enable it but I couldn't.
It isn't really possible.
The RESTeasy approach relies on a combination of reflection and annotations to determine what the REST interface is.
When using Vert.x Web routes you have more flexibility which that that level of information isn't available in a standard way.
There are a couple of alternatives:
Write the OpenAPI definition up front and use that to generate the routes (https://how-to.vertx.io/web-and-openapi-howto/)
Find (or write) a generator that constrains your Vert.x code so that it can determine the contract dynamically (https://jitpack.io/p/ckaratzas/vertx-openapi-spec-generator is an example, it may not be the only one).
Personally I use RESTeasy if I need to generate OpenApi docs.
how does one combine multiple swagger documents? The documents generated from multiple endpoints need to be made available in a HTML UI.
You could use the following tool I wrote: https://www.npmjs.com/package/openapi-merge-cli
I am learning about RIAK and thinking about using it to store JSON objects.
I have also used swagger UI many times in the past to document API's.
I would like to build a simple example bucket in RIAK with a swagger UI style API. This could be simple out of the box functionality. All I need to do is define a model for the JSON object and it should be possibly to automatically create a swagger file with get, post, put options for that object.
I have googled "swagger Riak" but I can't find any articles with both words in them.
Is there a better phrase I should be searching for?