Choose an OpenAPI generator library

[emmdim]

Choose an OpenAPI generator library evaluating:

• Information included : URL, URL variable, Errors
• Presentation of information in relation with how it is presented in the Documentation

[selankon]

Following @altergui instructions, I tried swago (from vocdoni node repo):

cd api
go get github.com/swaggo/swag/cmd/swag
go run github.com/swaggo/swag/cmd/swag init --parseDependency --parseDepth 1 --parseInternal -g api.go

This generate a Yaml swagger specification, I found the following problems:

1. It don't pass the swagger schema validation because it misses some needed attributes. Paste de swagger here to see errors. For example:

  /accounts:
    post:
      description: Set account information
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/components/schemas/blah'
      summary: Set account

Should be:

/accounts:
    post:
      description: Set account information
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/blah'
      summary: Set account

This causes that the generated docusaurus pages are broken.

2. We should add tags and info to be more complete. This is added on the commented code.
3. Path parameters are missing causing errors (we should define the parameters on the comments for paths like /censuses/{censusID}/export )
4. Response examples needs to be added

On conclusion, it seems that the only breaking issue is the first one, we have to see if is a swaggo problem or what. Apart of this, it seem we could document everything inside the code and generate the swagger automatically. We have to migrate all the existing documentation to there, and do more tests to see if something else will break.

For example, some endpoints need bearer auth tokens, we have to see if are correctly parsed.

[chilcano]

Thanks @selankon

The swaggo only support OpenAPI 2.0 spec (aka swagger 2.0) and for that you are having errors when parsing the generated yaml.

swaggo/swag#548

Anyway, please, could you paste here the yaml file generated? Also,
Could you confirm what OpenAPI specs version require Docusaurus?

Regards.

[altergui]

Anyway, please, could you paste here the yaml file generated?

https://raw.githubusercontent.com/vocdoni/vocdoni-node/3b4f3866e416b5730d32e11c73666665522344e6/api/docs/swagger.yaml

[chilcano]

Anyway, please, could you paste here the yaml file generated?

https://raw.githubusercontent.com/vocdoni/vocdoni-node/3b4f3866e416b5730d32e11c73666665522344e6/api/docs/swagger.yaml

Thanks @altergui
Definitively, the yaml generated is swagger: "2.0" and according that specs, the schemas are defined, that is not perfect, but it is fine for a first iteration.
I miss critical information: what is the API version. If we consider API layer as a product, then we must set a proper version to track the changes. We can add the commit-hash as well.

Now, we should check what OpenAPI version supports Docusaurus. @selankon any idea?

Regards.

[selankon]

Hi @chilcano

We are using a docusaurus package to generate the docs: https://github.com/PaloAltoNetworks/docusaurus-openapi-docs (is not a docusaurus feature).

Reading the README.md should work with Swagger 2.0 and OpenAPI 3.0. And in fact, I was using the generated Swagger 2.0 schema with the OpenAPI 3.0 annotation, which is an error.

After running it again with the correct tag I saw this message when generating the docs: [ReDoc Compatibility mode]: Converting OpenAPI 2.0 to OpenAPI 3.0, so it seems to perform some conversion underneath.

So, after correcting the tag, everything worked as expected and the generated pages seems working now!

BTW: swaggo/swag#548 (comment) swaggo has beta suport for OpenAPI 3.0 on April 6 :)

[chilcano]

If Docusaurus (and plugin) can process the generated swagger 2.0 yaml by default, then that is good news @selankon !!

This confirms that swaggo is the right library and meet our requirements. Right ?
A thing I'm missing is the VERSION.
Can we add VERSION to API implementation (golang code) and use it to generate a swagger yaml file as metadata and with Docusaurus generate API documentation for that specific VERSION ?

What do you think @altergui and @selankon ?

Regards.

[selankon]

Hi @chilcano

From the docs of swaggo it seems that a version tag could be added on the information section, for example.

And on docusaurus side we can generate different api docs for different versions using different yaml. So, it is possible to be done.

The only thing on all this system is that a lot of documentation are wrote on the code, maybe hindering readability. We have to balance if we want to move all documentation to the code (is also a good amount of work, easy but extended).

[chilcano]

That is great @selankon !!
Using Version, now we can track from code, to swagger and docusaurus documentation in the same cycle.
Well, as you sated before, we should clarify where document the API, in the code, in the generated swagger or in the docusaurus documentation.

IMO, I think that the golang code should have a minimum documentation (in the golang code itself), that should generate an initial swagger yaml file that can be used in the subsequent processes such as publish it as it or enrich it to be published on developer portal as Docusaurus documentation.

What do you think?

[chilcano]

Extra resources to enrich the API documentation based:

• https://docusaurus-openapi.tryingpan.dev/petstore/pet/
• https://github.com/swaggo/swag#general-api-info
• https://github.com/swaggo/swag#how-to-use-it-with-gin

--markdownFiles value, --md value      Parse folder containing markdown files to use as description, disabled by default
--codeExampleFiles value, --cef value  Parse folder containing code example files to use for the x-codeSamples extension, disabled by default

Next steps:

1. Add extra info to endpoint in the golang code
2. Add API metadata (version, description, etc)

Ref: #65

[selankon]

FTR codeExampleFiles option is used to give code samples like curl so is not needed for us