eclipse / microprofile-open-api

Microprofile open api

Eclipse MicroProfile OpenAPI

This MicroProfile specification aims at providing a unified Java API for the OpenAPI v3.1 specification, that all application developers can use to expose their API documentation.

• The spec APIs are composed of annotations, models, and programming interfaces.

• The spec documentation outlines the rules and boundaries of the spec.

• To chat or ask questions about the spec, join the discussion on Gitter:

• For announcements, visit the MicroProfile Google Group.

• Extended examples that supplement the spec can be found here.

• Eclipse release information and further logistics about the project can be found here.

How to contribute

Do you want to contribute to this project? Here is what you can do:

• Fork the repository, make changes, then do a pull request.

  • Remember to sign your commits

  • Make sure you have signed the Eclipse Contributor Agreement

• Create or fix an issue.

• Join us on Gitter to discuss this project.

• Join our weekly meeting (UTC / US Eastern time).

  • Minutes and Agenda.

• Join the discussions on the MicroProfile Google Group

• Contribute a blog post.

Also see the MicroProfile Contributing Guidelines on the Eclipse MicroProfile wiki page and the CONTRIBUTING page.

microprofile-open-api's Issues

TCK test for OASModelReader

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.

Server configuration injection

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).

TCK Annotation coverage

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:

• check the box of the ones you want to work on
• put a comment saying you're working on Annotation x, y and z.
• investigate if the annotation usage in our sample apps cover the corresponding OpenAPI element from the spec (https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md)
• If not, then either update the current usage or create a new resource/class within the app that makes use of that annotations, and then update the expected output of the TCK.

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:

• https://github.com/swagger-api/swagger-samples/tree/2.0
• https://github.com/swagger-api/swagger-core/tree/2.0/modules

Annotation list:

• Callback
• Callbacks
• Components
• Explode
• ParameterIn
• ParameterStyle
• SecuritySchemeIn
• SecuritySchemeType
• Extension
• Extensions
• ExternalDocumentation
• Header
• Contact
• Info
• License
• Link
• LinkParameter
• ArraySchema
• Content
• DiscriminatorMapping
• Encoding
• ExampleObject
• Schema
• OpenAPIDefinition
• Operation
• Parameter
• Parameters
• RequestBody
• APIResponse
• APIResponses
• OAuthFlow
• OAuthFlows
• OAuthScope
• SecurityRequirement
• SecurityRequirements
• SecurityScheme
• SecuritySchemes
• Server
• Servers
• ServerVariable
• Tag
• Tags

Clearly document expected behaviour of setRef()

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");

Add architecture diagram

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.

TCK for configuration options

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.

Release rc1

Planned for Dec 6, a release candidate of API and spec.

Introduce models

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.

OpenAPI SecurityRequirement does not allow to define set of requirements

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

TCK tests for static files

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.

Define way of providing extra vendor specific configuration

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

Link model requestBody field should be String or Object

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.

Address maven build failures from 'checkstyle' and 'javadoc' plug-ins

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.

Remove ArraySchema annotation

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)

TCK tests for openapi endpoint

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.

TCK test for OASFilter

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.

Improve model by adding enums to place such Parameter.in, or SecurityScheme.type

Instead of using String add enums to improve user experience and chance of usage errors

Add annotation samples to the spec

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

Create specification document outline

Create specification document outline for further collaboration on documentation

Add annotation support

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

Publish jars to appropriate repository

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.

Add a "Filterable" interface

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.

test

was-liberty/open-liberty#1153

Add Javadoc to org.eclipse.microprofile.openapi.models.Constructible.

Add a description to the org.eclipse.microprofile.openapi.models.Constructible interface that specifies its relationship with the OASFactory.

Introduce filter capability

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

Improving Tag and Tags annotations

@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:

• Adding the ref @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.

• Adding the ref s@Tags for easy referencing multiple tags:

org.eclipse.microprofile.openapi.annotations.tags.Tags:
public @interface Tags {
    ...
    String[] refs() default {};
}

Create a TCK

We'll need a TCK for this specification. It should exercises the different parts of the spec.

Add default value for ParameterIn enum inside annotation

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

Define endpoint to retrieve OpenAPI document

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.

Update annotation and models with spec links

Most of our annotations and model don't have a corresponding OAS spec link.

De-dupe annotations with available API from Swagger

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.

Describe behaviour of appending context roots

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)

Callback model should implement Reference interface

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 for OASFilter

Once we have #6, we should add a sample to the OpenAPI spec wiki.

Specific an opinion on internationalization

We don't need to mandate a solution, but the spec should at least mention this in the limitations section

Port PetStore app into TCK

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

Parameter model should be constructible to enable reference parameters

Example:

parameters:
 - $ref: '#/components/paramters/MyParam'
 - $ref: '#/components/paramters/MyParam2'

OASFactory.createObject(Parameter.class).ref("myParam2")

additionalProperties only supports Schema

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

Port airlines application into TCK

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.

Factor out base interface for 'reference' objects.

Proposed interface:
public interface Reference<T extends Reference> {
String getRef();
void setRef(String ref);
T ref(String ref);
}

Fix the build

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.

Allow configuration of annotation processing

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).

ServerVariable annotation enumertion default value should be {}

Create a sample of the OASModelReader

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

Specify design-first scenarios

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.

OASFactory.INSTANCE ignores the resolver set

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.

Parameters in Link model should be of type Map<String, Object>

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.

Write a sample for the annotation configuration

Write a sample in the wiki that demonstrates how to configure the annotation processor

Update Schema annotation with enum for type field

Minor spec updates to RC1

• 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.