fusionauth-openapi's Introduction

FusionAuth OpenAPI

This is an OpenAPI specification for the FusionAuth API.

Here's the openapi specification YAML file.

It can be used in a variety of contexts, including generating client libraries, tracking API changes over time and testing. More here: https://openapi.tools/

Use this file to do all your OpenAPI related actions. For additional information and documentation on FusionAuth refer to https://fusionauth.io.

Generate libraries
Java
Ruby
Test the YAML
Postman Collection
Known issues
Next steps
Questions and support
Contributing
License

Generate libraries

Install either Swagger: https://github.com/swagger-api/swagger-codegen/ or openapi: https://github.com/OpenAPITools/openapi-generator

These instructions will be for openapi.

Java

To build the java client libraries:

bin/java/build.sh

This will produce a jar you can use.

Ruby

To build the ruby client libraries:

bin/ruby/build.sh

Read the readme in ruby/README.md for installation and usage instructions. To install it as a gem locally using --dev, I had to build it and then install a couple of rspec dependencies by hand.

More docs here: https://openapi-generator.tech/docs/generators/ruby

Dart

To build the dart client libraries:

bin/dart/build.sh

This will produce a dart package you can import.

Test the YAML

pip3 install schemathesis # one time
schemathesis run -vvvv --checks not_a_server_error openapi.yaml --base-url http://localhost:9011 -H "Authorization: bf69486b-4733-4470-a592-f1bfce7af580"

Postman Collection

You can also explore around with our API in postman.

Here's our Postman profile and public workspace.

Import Postman Collection

Log into the FusionAuth Postman team
Click the Import button on the left hand nav, toward the top
Import the API definition. This should also create a new collection
Rename the API and collection with the correct API version
Copy over the description from a previously imported API (easiest to do it in two tabs)
Copy the new collection into the workspace.
Go to the FusionAuth Postman homepage and edit the new collection and put the date on it.

Known issues

While the specification is valid, the generated client libraries haven't been fully exercised.

FusionAuth uses polymorphic responses for some API calls, particularly Identity Providers. The support for that in client library generation code is problematic, based on our testing. I'm not sure if there are workarounds, but it seems like some work is being done. See swagger-api/swagger-codegen#10011 and OpenAPITools/openapi-generator#10880 (comment) for an openapi workaround.
This spec is built using the fusionauth-client-builder project JSON files. This covers almost all of the API, but not everything. A few calls may be missing. If you find one that you need, please open a bug report.
Deprecated API endpoints are not included.
There's no information about what parameters are required or not, because that is not part of the API JSON files.
There are certain operations, status codes and security mechanisms (JWT auth, cookies for auth) that are not currently supported because they are not included in the API JSON files.
OAuth grant actions aren't currently supported (the /oauth2/ endpoints).
There is an issue generating the ruby client libraries. OpenAPITools/openapi-generator#11350 has the repro steps. The RUBY_POST_PROCESS_FILE environment variable is a workaround.

Next steps

We are publishing this to see how useful the FusionAuth community finds it. We welcome feedback on your usage of this spec. We'll plan to revisit this after we've received some feedback on how useful it is and determine if there are additional features we need to implement.

Please open bugs on this repository. For support in using this, please see the next section.

Questions and support

If you have a question or support issue regarding this OpenAPI spec, we'd love to hear from you.

If you have a paid edition with support included, please open a ticket in your account portal. Learn more about paid editions here.

Otherwise, please post your question in the community forum.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/FusionAuth/go-client.

If you find an issue with syntax, etc - this is likely a bug in the generation script. Feel free to submit a PR against the Client Builder project.

License

The code is available as open source under the terms of the Apache v2.0 License.

fusionauth-openapi's People

Contributors

Stargazers

Watchers

fusionauth-openapi's Issues

GithHub Actions suddenly started to fail

Since June 7th, the Validate YAML workflow has been failing but we didn't make any changes to the spec at all.

OAS type inconsistency

I have noticed a type inconsistency between the OAS docs for the API and the actual usage and example usage of the API.

This is based on the current API spec at https://github.com/FusionAuth/fusionauth-openapi/blob/master/openapi.yaml

This same issue appears across multiple components but for a concrete example in the User component expiry field:

expiry:
"$ref": "#/components/schemas/ZonedDateTime"

The field reference is for a type of ZonedDateTime but the actual type is a numeric (long)

In the example response displayed on this page - https://fusionauth.io/docs/v1/tech/apis/users#reactivate-a-user - you can see that "expiry" is in fact numeric with no timezone representation and not a ZonedDateTime

Open API Missing BaseSAMLv2ApplicationConfiguration when building

Examples from autorest and openapi-client below.

(test) ➜  openapi-client git:(fusionauth-openapi) ✗ autorest --input-file=../../openapi/fusionauth.yaml --python  --namespace=fusionauth 
AutoRest code generation utility [cli version: 3.6.3; node: v18.14.0]
(C) 2018 Microsoft Corporation.
https://aka.ms/autorest
info    | AutoRest core version selected from configuration: ^3.7.0.
info    |    Loading AutoRest core      '/Users/richard/.autorest/@[email protected]/nodemodules/@autorest/core/dist' (3.9.4)
info    |    Installing AutoRest extension '@autorest/python' (latest -> 6.4.0)
installing... [========================================] 100% | 16/16
info    |    Installed AutoRest extension '@autorest/python' (latest->6.4.0)
info    |    Loading AutoRest extension '@autorest/modelerfour' (~4.23.5->4.23.7)
error   | InvalidRef | Ref '#/components/schemas/BaseSAMLv2ApplicationConfiguration' is not referencing a valid location. components,schemas,BaseSAMLv2IdentityProvider,properties,applicationConfiguration,additionalProperties
    - file:///Users/richard/dev/authentication-service/openapi/fusionauth.yaml:6873:11
fatal   | Plugin 'full-ref-resolver' completed with some error.
error   |   Error: Plugin 'full-ref-resolver' completed with some error.
error   | Autorest completed with an error. If you think the error message is unclear, or is a bug, please declare an issues at https://github.com/Azure/autorest/issues with the error message you are seeing.

Openapi-generator

(test) ➜  openapi-client git:(fusionauth-openapi) ✗ openapi-generator generate -i ../../openapi/fusionauth.yaml -g python -c fusionauth.config.yaml 
Exception in thread "main" org.openapitools.codegen.SpecValidationException: There were issues with the specification. The option can be disabled via validateSpec (Maven/Gradle) or --skip-validate-spec (CLI).
 | Error count: 1, Warning count: 131
Errors: 
        -attribute components.schemas.BaseSAMLv2IdentityProvider.BaseSAMLv2ApplicationConfiguration is not of type `schema`
Warnings: 
        -attribute components.schemas.BaseSAMLv2IdentityProvider.BaseSAMLv2ApplicationConfiguration is not of type `schema`

        at org.openapitools.codegen.config.CodegenConfigurator.toContext(CodegenConfigurator.java:620)
        at org.openapitools.codegen.config.CodegenConfigurator.toClientOptInput(CodegenConfigurator.java:647)
        at org.openapitools.codegen.cmd.Generate.execute(Generate.java:465)
        at org.openapitools.codegen.cmd.OpenApiGeneratorCommand.run(OpenApiGeneratorCommand.java:32)
        at org.openapitools.codegen.OpenAPIGenerator.main(OpenAPIGenerator.java:66)

Internal -> tickets - 73173

Recommend Projects

fusionauth / fusionauth-openapi Goto Github PK