[hardwaresofton]

Hey you might want to note a bit more about what exactly this does and how it does it on the README. I went to the page and was thoroughly confused -- does this library:

- Read application code (written in python?) and extract an API specification? Is it flask only?

- Does it update the file on disk repeatedly?

- Does it modify generated application code to add an endpoint for the Swagger UI and host it?

- Are any modifications to the pre-existing applications necessary?

- Does it wrap an existing application?

Good tools also often have a comparison section -- are there other tools in your space that do what you do, but differently?

I'd like to think I'm familiar with the Swagger/Swagger2/OpenAPI3 space, and I'm aware of tools that go spec->code (usually generating clients/servers) and code->spec (whether by comments, annotations, or some other language mechanism), but it's not clear what your tool actually does.

[yehors]

Hello. Yes, I have not prepared enough the description so guys and ladies I am sorry for that. Just added more information to the README.md file on GitHub.

Answers to the questions:

> - Read application code (written in python?) and extract an API specification? Is it flask only?

You can:

1. Construct schema objects and request objects using Python classes with marshmallow [1] library;

2. Split API paths (routes) into separate python modules, files for convenience and then add them in the `api/project.py` file.

> - Does it update the file on disk repeatedly?

No. You need to re-build the `api.yaml` file by yourself, using this command: "python build.py"

> - Does it modify generated application code to add an endpoint for the Swagger UI and host it?

No. You need to write the business logic of your API by yourself. For example, you write an API in Go and describe the API definitions (specifications) using my project just by adding new paths, schemas. Flask is used only for development purposes, it is not meant to create API using Flask, but you can do it as well.

> - Are any modifications to the pre-existing applications necessary?

No.

> - Does it wrap an existing application?

If you meant if this is a wrapper for other apps then it is. These two: marshmallow [1] and apispec [2]

If you meant if this wraps existed API then the answer is yes. You can describe existing APIs using my project.

> ... are there other tools in your space that do what you do, but differently?

Yes, a lot and for many languages. I can mention swagger-php [3], flask-swagger [4] which I know. But the two are using annotations in code (via docstrings) to describe the API definitions/specification when my project is meant to create ONLY API defs/spec.

[1]: https://marshmallow.readthedocs.io/en/stable/

[2]: https://github.com/marshmallow-code/apispec

[3]: https://github.com/zircote/swagger-php

[4]: https://pypi.org/project/flask-swagger/

[hardwaresofton]

Thanks for the detailed answers!

You know what would make it really clear -- a "Quick Start" section, show me how to go from 0 to 1 with your library.

From what I can gather:

- `pip install` your library

- create a golang project

- write some routes (and annotate them accordingly)

- call your library via `python ...` (?)

- api.yaml is written to my directory

Thanks for open sourcing this software!

[yehors]

This quote came to my mind after your comment: "It is necessary to light it up so that it shines. (Inscription on Kubachi lamps)".

Yesterday I extended the README file so you can start using information from this section: https://github.com/egorsmkv/openapi3-generator#how-to-use

As I said before the project isn't related to business logic of your APIs but I can show you an example how you could use it. It's an example about how to create an API in Go.

After generating an api.yaml file go to api-spec-converter [1] and convert content of API spec in OpenAPI 3 format to Swagger 2.

Then download an executable file of go-swagger [2] and run this command to generate all boilerplate code for your server:

swagger generate server -f ./swagger.json -A pet-api

This way you can firstly prototype (describe all paths, schemes, and requests) of your API and only then to start to write code. It's hugely simplifying the process of coding in my opinion.

[1]: https://lucybot-inc.github.io/api-spec-converter/

[2]: https://github.com/go-swagger/go-swagger

[hardwaresofton]

Thanks for going above and beyond on the documentation -- I finally understand exactly where it fits!