eclipse / microprofile-open-api Goto Github PK
View Code? Open in Web Editor NEWMicroprofile open api
License: Apache License 2.0
Microprofile open api
License: Apache License 2.0
Similar to issue #61 we will need to port the PetStore app into the TCK (using MP OpenAPI annotations instead of Swagger annotations).
We should grab the best sample from within this repo: https://github.com/swagger-api/swagger-samples/tree/2.0/java
Planned for Dec 6, a release candidate of API and spec.
Example:
parameters:
- $ref: '#/components/paramters/MyParam'
- $ref: '#/components/paramters/MyParam2'
OASFactory.createObject(Parameter.class).ref("myParam2")
We'll cover the mp.openapi.model.reader
and mp.openapi.filter
configuration options via other issues, but we'll need to cover all the other mp.openapi.* options in our TCK tests.
This issue will track the inclusion of such tests, and their expected outputs.
Instead of using String add enums to improve user experience and chance of usage errors
Add a description to the org.eclipse.microprofile.openapi.models.Constructible interface that specifies its relationship with the OASFactory.
We need to plug into MicroProfile's repository so that the jars we have in this spec (annotations, models, programming interfaces, etc) are available in the proper place.
We will be using the /openapi
endpoint for most of our TCK tests already, but this issue will track the inclusion of specific endpoint tests that will use different Accept
headers for json and yaml.
We need a new set of TCK tests that covers the OASModelReader. For simplicity it should use META-INF/microprofile-config.properties to point to the implementation of OASModelReader we're testing.
We need to have tests that add a complete model (with annotation scanning turned off), as well as tests that add a stub model (that boostrap the annotations).
The expected output should be changed accordingly.
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#linkObject
Right now its of type RequestBody but specification states a literal Any | {expression} type.
We'll need a TCK for this specification. It should exercises the different parts of the spec.
Most of our annotations and model don't have a corresponding OAS spec link.
OAS introduced the concept of a server object (global-level array and operation-level array). We need to see how devs can inject the server information using MP Config 1.1. This should work in a variety of scenarios (standalone, kubernetes, cloud foundry, etc).
We introduced the OASFilter, which allows certain model elements to be filtered.
To make it clear that a certain element will be called via a filter (if any are registered), we should introduce a new interface called "Filterable" that is implemented by any OpenAPI element that can be filtered.
As part of this issue, the spec section called "OASFilter" should be updated.
https://ci.eclipse.org/microprofile/job/OpenTracing-maven-snapshots/
I disabled the build, since no one was fixing it. It had been failing for about 2 weeks.
According to the spec the value of the additionalProperties
is:
Value can be boolean or object. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema.
Our model currently only allows Schema
Once we have #6, we should add a sample to the OpenAPI spec wiki.
This issue will add OpenAPI v3 annotations that allow users to document their RESTful application. It should cover the entire spectrum of the OpenAPI v3 specification
We need to introduce OAS models (as interfaces) so that we can work with the OAS tree during annotation processing. These models should be able to be chained, as well as created independently.
We also need a factory to create these.
Proposed interface:
public interface Reference<T extends Reference> {
String getRef();
void setRef(String ref);
T ref(String ref);
}
An architectural diagram of the different parts of the spec would help readers understand its scope. That fits under the "Architecture" portion of the spec.
Most users of OpenAPI are familiar with the Swagger annotations. By duplicating these annotations, which are just representations of the spec, we're creating portability problems for users who may already be using the annotations, as well as introducing extra complexity by needing to switch between the two.
@Tag
and @Tags
annotations can be defined in one JAX-RS resources class and used in other classes. In the open source Swagger annotation definition, it is confusing how to refer to tags in different annotations.
Here is the proposal:
@Tag
:org.eclipse.microprofile.openapi.annotations.tags.Tag:
public @interface Tag {
...
String ref() default "";
}
If ref
field is defined in a @Tag
, there is no need to define the name
field.
@Tags
for easy referencing multiple tags:org.eclipse.microprofile.openapi.annotations.tags.Tags:
public @interface Tags {
...
String[] refs() default {};
}
Example of $ref to callback
openapi: '3.0.0'
info:
title: API
version: 1.0.0
paths:
/path:
get:
description: 'Path with callback'
responses:
200:
description: 'ok'
callbacks:
simpleCallback:
$ref: '#/components/callbacks/simpleCallback'
components:
callbacks:
simpleCallback:
'/mycallback':
get:
responses:
200:
description: 'ok'
Write a sample in the wiki that demonstrates how to configure the annotation processor
We need a new set of tests for using static (pre-generated) files in META-INF/openapi.
There should be tests where the file is complete (ie: with annotation support turned off), as well as hybrid tests where the static file is supplemented by either the OASModelReader or annotations.
We don't need to mandate a solution, but the spec should at least mention this in the limitations section
This spec needs to define an endpoint that will return the OpenAPI document that was generated from the processing of the annotations + models.
I propose that the endpoint be /openapi
, with a default Content-type of application/yaml
but also supporting application/json
Content requests.
This would mean that any implementation of MP OpenAPI would expose this endpoint.
In many scenario (ie: banks) the OpenAPI specification will be designed before the microservice code starts. This means that an openapi.yaml (or JSON) file will be available.
Even though this scenario won't use annotation processing, there are some things we should specify in this spec:
(1) where does the app dev include this in their app? (ie: in order to view it in a UI, or to use it as a proxy/gateway for their app)
(2) how does the app dev inject dynamic values, such as the server's URL, into the document?
For (1), I propose that the specification state that documents inside META-INF/openapi with the extension of either YAML | YML | JSON will be processed - first one wins
, so include just one.
For (2), we can use the injection of servers (#7) or alternatively use a filter (#6) to augment the document with dynamic values.
We need to introduce a Filter service/interface that would allow application developers to take control before/during/after the annotation processing stage.
This means that dev have the flexibility to programmatically start an OAS tree that the processor uses, or filter certain operations/objects dynamically. Devs could even do a "model-only" approach, which would turn off annotation processing.
Proposed name: OASFilter
Create specification document outline for further collaboration on documentation
As a improvement for user experience it should be allowed to provide a short reference name:
This should be clearly defined in specification document
Example:
// #/components/parameters/userId
parameter.setRef("userId");
// #/components/responses/NotFound
response.setRef("NotFound");
// user also can provides a full reference
response.setRef("#/components/responses/NotFound");
was-liberty/open-liberty#1153
Porting airlines app (https://github.com/microservices-api/oas3-airlines) to use MicroProfile OpenAPI and to live inside the TCK.
Needs to be able to run via the TCK.
Right now the current enum forces user to provide a type even if its already provided by
@QueryParam, @PathParam
, etc JAX-RS annotations
Add DEFAULT("") to the values
Example document:
openapi: '3.0.0'
info:
title: API
version: 1.0.0
paths:
/oneOrOther:
get:
description: ''
responses:
200:
description: ''
security:
- oauth_implicit: []
- api_secret: []
/both:
get:
description: ''
responses:
200:
description: ''
security:
- api_secret: []
oauth_implicit: []
components:
securitySchemes:
oauth_implicit:
type: oauth2
flows:
implicit:
authorizationUrl: "https://localhost/"
scopes:
full: "Full Access"
api_secret:
type: apiKey
name: api-secret
in: header
Currently version in endpoint /both is not possible.
Need to add a container, such as SecurityRequirementsSet
We should allow the configuration of annotation processing via MP Config, for example, which packages to scan (improves performance for large apps).
For example, a dev should be able to do this inside META-INF/microprofile-config.properties
openapi.packagesToScan=abc,def,
openapi.server=myhost:8443
...
openapi.filter=mypackage.myFilter
The implementation of this spec would get those values injected (or can manually query for them).
If you set the resolver via OASFactoryResolver.setInstance
, that resolver is not used by invocations to the factory. The value is set when the class is loaded.
Instead, you should just ask for the resolved instance on each invocation. I also wonder if this class should be an API, with methods defined, instead of being a static factory? Maybe a different issue.
This issue tracks the completion of the section "Detailed usage of key annotations" of the spec.
For each of the key annotations we need to write a bit more information on its usage scenario and have at least 1 sample (more would be better), of the Java annotation itself + generated output.
Something similar to the samples in the Swagger wiki: https://github.com/swagger-api/swagger-core/wiki/Annotations-2.X
Running 'mvn install' on the current code in arthurdm/master is generating many warning and errors from the 'checkstyle' and 'javadoc' plug-ins. We should review and resolve these issues. I'll be pasting the output from my build(s) here, but of course the actual list of issues will change from day-to-day as we keep updating the repository. Once we get this cleaned up folks should make sure that they do a build before they submit a PR so that we keep it clean going forward.
The spec should define an expected behaviour in terms of whether the context root of an application is present in every PathItem or if that context root goes into the server URL.
Our proposal is for the context root to be present in the server URL (much like basePath in v2)
Our TCK will have 2 core input applications: Airlines (issue #61) and PetStore (issue #64)
This issue will track the investigation of TCK coverage for each OpenAPI annotation.
So for each of the annotations in the list below:
If you're wondering what kind of coverage a particular annotation could have, here are 2 repositories that contain many of the same annotations (just different packages). Search for tests and samples that use them:
Annotation list:
We need a set of tests for the OASFilter API. For simplicity, configure it using META-INF/microprofile-config.properties.
We'll need to change the expected output accordingly.
This sample should showcase how an app dev would contribute a model tree (either complete or partial), using the OASModelReader
.
Here's an example from the Swagger repositories on a similar approach: https://github.com/microservices-api/oas3-configuration/blob/master/sample.oas.programmingModels/src/io/swagger/sample/config/OpenAPIConfigurationImpl.java#L23
Define a common way to provide extra properties for different vendors using MicroProfile config
For example:
openapi.extension = { myExt: myValue}
or
openapi.extension.myExt = myValue
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#linkObject
parameters filed is Map[string, Any | {expression}]
So we should switch to Object for consistency with rest of the models.
Fix annotation samples where we're using older values from the Swagger library (e.g. the allowableValues
field from ServerVariable).
Move the validation paragraph into the limitations section.
Add a section about CORS in the limitations section
Update the spec to have the new @CallbackOperation
annotation.
Now that RC1 is out (http://download.eclipse.org/microprofile/microprofile-open-api-1.0-RC1/microprofile-openapi-spec.html), this issue will go through it and make the updates.
Remove ArraySchema annotation and reference to it.
AllOff, oneOf and other schema properties use Java class for definition.
We should keep that consistent with array schemas as well
Usage difference:
Instead of using array=@ArraySchema(schema=@Schema)
For simple types:
@Schema(type="array", implementation=String.class)
For complex types:
@Schema("customize Todo schema" )
public class Todo {
}
@Schema(type="array", customize array schema, implementation=Todo.class)
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.