https://github.com/kevinoid/appveyor-swagger
Unofficial AppVeyor REST API Swagger Definition
https://github.com/kevinoid/appveyor-swagger
appveyor openapi-specification schema swagger
Last synced: about 1 month ago
JSON representation
Unofficial AppVeyor REST API Swagger Definition
- Host: GitHub
- URL: https://github.com/kevinoid/appveyor-swagger
- Owner: kevinoid
- License: mit
- Created: 2016-12-21T03:16:03.000Z (almost 9 years ago)
- Default Branch: main
- Last Pushed: 2023-05-18T06:57:27.000Z (over 2 years ago)
- Last Synced: 2025-04-13T03:08:00.132Z (6 months ago)
- Topics: appveyor, openapi-specification, schema, swagger
- Size: 1.87 MB
- Stars: 8
- Watchers: 3
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
Unofficial AppVeyor REST API Swagger Definition
===============================================
[](https://ci.appveyor.com/project/kevinoid/appveyor-swagger)
[](https://github.com/swagger-api/validator-badge)
[](https://www.npmjs.com/package/appveyor-swagger)
This project aims to provide a
[Swagger](http://swagger.io)/[OpenAPI](https://www.openapis.org/) definition
of the [AppVeyor REST API](https://www.appveyor.com/docs/api/). It is
neither supported nor endorsed by AppVeyor. Any differences between this
definition and the AppVeyor REST API are errors in this definition and users
are encouraged to [report the
issue](https://github.com/kevinoid/appveyor-swagger/issues/new).
## Documentation
The documentation generated from the Swagger definition is available in the
following formats:
* [ReDoc](https://github.com/Rebilly/ReDoc):
[AppVeyor API Docs](https://kevinoid.github.io/appveyor-swagger/redoc/)
(Supports `discriminator`)
* [Swagger UI](https://github.com/swagger-api/swagger-ui/):
[AppVeyor API Docs](https://kevinoid.github.io/appveyor-swagger/swagger-ui/)
* [Bootprint](https://github.com/bootprint/bootprint-openapi):
[AppVeyor API Docs](https://kevinoid.github.io/appveyor-swagger/bootprint/)
## Installation
The Swagger definition can be installed as an [an npm
package](https://www.npmjs.com/package/appveyor-swagger) by running:
```sh
npm install appveyor-swagger
```
It can then be used in [Node.js](https://nodejs.org/en/) projects with:
```js
var appveyorSwagger = require('appveyor-swagger');
```
## Test Client
There is a [AppVeyor API Client in
Java](https://github.com/kevinoid/appveyor-swagger-java) which is generated
from the definition in this project and used for demonstration and testing
purposes. It is a good example of how to generate and use a client based on
this definition.
## Implementation Notes
### Versioning
The AppVeyor REST API does not provide any public versioning scheme that I am
aware of. Since versioning is necessary, both in the OpenAPI specification
file and in the npm package, this package attempts to apply the rules of
[Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) to code
generated from this OpenAPI definition to determine appropriate version
numbers.
Since generated code varies based on the code generator and settings
used, the definition of what constitutes a backward-compatible API change is
subjective. The version numbering will be conservative, such that the major
version number is incremented for potentially- and selectively-incompatible
generated API changes. Users who encounter changes which violate semantic
versioning expectations are encouraged to report the issue so the version can
be incremented accordingly.
### Schema Names
The schema names used in the definition are based on the names returned in the
XML API responses, where those names are not confusing and do not conflict
with the requirements imposed by `discriminator`. (The OpenAPI Spec requires
`discriminator` property values match schema names).
### Schema Strictness
There are many trade-offs between the schema strictness and the usability,
clarity, and flexibility of the code generated by the schema. This project
attempts to make the types as strict as possible without compromising
usability and clarity. This provides the most type safety (for strictly typed
languages) and protection against accidental API misuse. Specific choices are
described below.
#### `With` Schema Types
The `DeploymentEnvironment`, `Project`, and `Role` schemas each have a second
schema which defines additional properties
(`DeploymentEnvironmentWithSettings`, `ProjectWithConfiguration`,
`RoleWithGroups`). The advantage to having separate types is both clarity in
the generated documentation and protection against misuse. For example,
trying to update a project using the `Project` instead of
`ProjectWithConfiguration` can be caught either at compile time or before the
request is made. The disadvantage is that since the generated `With` classes
do not implement or inherit from the class/interface of their parent schemas
and do not provide copy constructors between them, using them becomes more
painful. I would appreciate feedback about this trade-off in real-world use
cases.
#### `PUT` vs `GET` Schema Types
`PUT` schemas could be defined separately from the `GET` types in several
cases. This would allow making most properties `required` in the `GET` types,
which could result in non-nullable/non-optional codegen in some languages
(although it does not in any that I'm currently aware of). The down-side is
that unless the codegen includes an easy way to translate data between these
types, doing a `GET`+modify+`PUT` becomes more painful than it should be. So
this has been not been done.
### Polymorphism
`swagger-polymorphic.yaml` attempts to provide stricter type definitions by
applying polymorphism using the
[`discriminator`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#user-content-schemaDiscriminator)
property. Most tools provide limited or no support for this property.
Therefore, this file is mostly kept for reference and in the hopes that future
tools may be able to make use of it.
Polymorphic types are problematic for several reasons, not least of which is
the requirement that Schema name match the `discriminator` property value,
which can cause collisions and require ugly names.
[OAI/OpenAPI-Specification#403](https://github.com/OAI/OpenAPI-Specification/issues/403)
There are various extensions available:
* AutoRest uses
[`x-ms-discriminator-value`](https://github.com/Azure/autorest/pull/474)
* Swagger Codegen has an open PR to use
[`x-discriminator-value`](https://github.com/swagger-api/swagger-codegen/pull/4252)
There are also plans to support `oneOf` and `anyOf` in OpenAPI v3.0
[OAI/OpenAPI-Specification#741](https://github.com/OAI/OpenAPI-Specification/pull/741)
along with adding a value to type map for `discriminator`. This may solve the
above issues.
### Shared responses
The next version of the spec includes support for version ranges using `4XX`
notation
([OAI/OpenAPI-Specification#638](https://github.com/OAI/OpenAPI-Specification/pull/638)).
There is also discussion of including a mechanism for defining default
responses in
[OAI/OpenAPI-Specification#521](https://github.com/OAI/OpenAPI-Specification/issues/521)
and
[OAI/OpenAPI-Specification#563](https://github.com/OAI/OpenAPI-Specification/issues/563)
Unfortunately, since neither of these is supported in OpenAPI v2.0, the
definition in this project contains a redundant error response definition for
error for each API path.