How to generate API docs with openapi-generator.tech

Question

I am playing around with https://openapi-generator.tech/ and I have an example openapi.yaml file:

openapi: 3.1.0

info:
  title: Sample API
  description: My amazing description.
  version: 0.0.9

servers:
  - url: http://localhost:8080/v1
    description: My amazing server description.

paths:
  /users:
    get:
      summary: Returns a list of all users.
      description: My amazing /users endpoint description.
      responses:
        "200":
          description: (OK) A JSON array of user objects.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

I have tried the following generation command:

openapi-generator-cli generate -g go-gin-server --global-property=apiDocs=true -i ./openapi.yaml

both with, and without the --global-property=apiDocs=true part. Neither case generated an /api, /doc, or /docs endpoint.

What am I doing wrong?

Note that the server runs fine, i.e., I can curl the endpoints specified in the yaml file.

Ben Borchard · Accepted Answer · 2022-11-02 15:32:41Z

1

It doesn't look like the server stub generator go-gin-server supports adding this type of endpoint. If you look at the routers template that this generator uses you can see that no config option will generate an /api, /doc or /docs endpoint unless you have defined it in your spec.

It's not clear to me exactly what you are expecting from this endpoint, but you could define one of these endpoints in your spec and implement the behavior you would like, or you could customize the template to automatically add this endpoint during code generation

edited Nov 2, 2022 at 15:32

answered Nov 2, 2022 at 14:58

Ben Borchard

6493 silver badges9 bronze badges

Sign up to request clarification or add additional context in comments.

2 Comments

dow Over a year ago

I would expect it to auto-generate the swagger docs for the API, since the yaml file provides all the information required, no?

Ben Borchard Over a year ago

Perhaps there are some server stub code generators that support that, but it appears go-gin-server does not. It probably wouldn't be hard to implement on your own though, there are a number of documentation generators you could hook in to your build process in the same place you will hook in the server stub code generation: nordicapis.com/7-open-source-openapi-documentation-generators

Collectives™ on Stack Overflow

How to generate API docs with openapi-generator.tech

1 Answer 1

2 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

2 Comments

Your Answer

Sign up or log in

Post as a guest

Related