Zły typ dla Device.lastIpv4 i regIpv4

User avatar
fracz
Posts: 1566
Joined: Fri Oct 28, 2016 10:56 pm
Location: Rybna

Thu Apr 11, 2019 12:51 am

Nie, zaufałem Ci :lol:

Intuicyjnie to teraz z tego w generatorach będzie wychodzić long, ale nadal trzeba się będzie domyślić że to ma być unsigned int (w "normalnym" użytkowaniu bez różnicy, te IP są tylko do odczytu).

Sprawdź: https://app.swaggerhub.com/apis/supla/s ... -api/2.3.0
magx2
Posts: 310
Joined: Wed May 17, 2017 1:27 pm
Contact:

Thu Apr 11, 2019 6:27 am

Ty modyfikujesz cały czas api 2.3.0? Nie powinieneś przypadkiem releasować 2.3.x?
magx2
Posts: 310
Joined: Wed May 17, 2017 1:27 pm
Contact:

Thu Apr 11, 2019 8:05 am

fracz wrote:
Thu Apr 11, 2019 12:51 am
Intuicyjnie to teraz z tego w generatorach będzie wychodzić long, ale nadal trzeba się będzie domyślić że to ma być unsigned int (w "normalnym" użytkowaniu bez różnicy, te IP są tylko do odczytu).
W sumie można dodać minimum: 0 do swaggera, wtedy nie będzie niejasności.https://swagger.io/docs/specification/d ... ata-types/
User avatar
fracz
Posts: 1566
Joined: Fri Oct 28, 2016 10:56 pm
Location: Rybna

Thu Apr 11, 2019 8:29 am

magx2 wrote:
Thu Apr 11, 2019 6:27 am
Ty modyfikujesz cały czas api 2.3.0? Nie powinieneś przypadkiem releasować 2.3.x?
Oj tam oj tam :lol: Teoretycznie w wersjach 2.3.x API się nie zmienia, więc wydawanie nowych docsów przy kolejnych minor releasach nie ma sensu. W tym przypadku to był błąd w dokumentacji i wydanie 2.3.1 wprowadzałoby w błąd, że wcześniej to był normalny int.
magx2
Posts: 310
Joined: Wed May 17, 2017 1:27 pm
Contact:

Thu Apr 11, 2019 8:46 am

No właśnie o to chodzi żeby dać znać że był błąd i go naprawiłeś. Wcześniej pytałem się czy sprawdziłeś generacje kodu, ponieważ myślałem że nowe API jest nie zrelesowane i sam nie mogę tego zrobić.

Inna sprawa w semantic versioning mamy X.Y.Z, gdzie X - major, Y - minor, Z - patch. Patch dokładnie oznacza, że był błąd w Z - 1 a w wersji Z go naprawiłeś. Dodatkowo wydana wersja nigdy nie powinna ulegać zmianie - ona jest już zapieczętowana. Ułatwia to pracę klientom twojego API. Ja ustawiłem sobie powiadomienia w Swagger Hub na temat nowych wersji i po każdym takim realease podbijam wersje JSuplaApi i OpenHABowego bindingu.
As a solution to this problem, I propose a simple set of rules and requirements that dictate how version numbers are assigned and incremented. These rules are based on but not necessarily limited to pre-existing widespread common practices in use in both closed and open-source software. For this system to work, you first need to declare a public API. This may consist of documentation or be enforced by the code itself. Regardless, it is important that this API be clear and precise. Once you identify your public API, you communicate changes to it with specific increments to your version number. Consider a version format of X.Y.Z (Major.Minor.Patch). Bug fixes not affecting the API increment the patch version, backwards compatible API additions/changes increment the minor version, and backwards incompatible API changes increment the major version.
https://semver.org/
User avatar
pzygmunt
Posts: 6630
Joined: Tue Jan 19, 2016 9:26 am
Location: Paczków
Contact:

Thu Apr 11, 2019 8:52 am

Używamy tego wersjonowania. W tym przypadku to był problem konfiguracji do dokumentacji. Nie dotyczy to kodu projektu. Inny przykład.... Gdyby uwzględniać konfigurację docker-a to też trzeba by inkrementować wersję. To wprowadza w błąd ponieważ kod/funkcjonalność się nie zmieniły. Nie poprawiono też błędu. Zmieniono "ozdobniki".

Co innego MINOR i MAJOR. Tutaj stosujemy zasadę, że wszystkie kompatybilne wersje systemu mają ten sam m i n. (wyjątkiem jest oprogramowanie układowe). Czyli jeżeli supla-cloud jest w wersji 2.3.X to

supla-server 2.3.X
supla-scheduler 2.3.X
iOS 2.3.X
Android 2.3.X
magx2
Posts: 310
Joined: Wed May 17, 2017 1:27 pm
Contact:

Thu Apr 11, 2019 9:23 am

pzygmunt wrote:
Thu Apr 11, 2019 8:52 am
To wprowadza w błąd ponieważ kod/funkcjonalność się nie zmieniły. Nie poprawiono też błędu. Zmieniono "ozdobniki".
Patrzysz na swaggera z perspektywy dewelopera Supla Cloud. Ja natomiast patrzę z perspektywy klienta (czyli drugiej strony kontraktu) i dla mnie został naprawiony bug - zamieniono inta32 na int64. Czyli patch powinien zostać podniesiony.

Inna sprawa sam Swagger Hub zabrania zmiany API po jego publikacji.
What does Publishing an API do?

When you create an API and make it available for users to consume, you are creating a contract for them. They rely on that definition to work a certain way, and breaking changes will potentially break their integrations.

Publishing an API is specific to a single version of an API. You should do so when the API ships and users can rely on the signatures. It tells your teams and consumers that your API is in a stable state. Once published, it is read-only and cannot be changed.

When published, you should consider making changes in a new version of your API.

After you publish, you may want to update the default version of the API. This is what is shown in search results, or when someone navigates to your API directly without a specific version number. You can learn more about versioning here.

Of course, there are always unforeseen situations where you may have a typo or need to make an emergency change. You can Unpublish your API but please do so carefully. Trust with your users is precious!
https://app.swaggerhub.com/faq
Post Reply