
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


== Usage Notes

Not all of the REST API exposed by the xref:vro:ROOT:about.adoc[REST API (Restful Objects viewer)] is included in the Swagger schema definition files; the emphasis is those REST resources that are used to develop custom apps: domain objects, domain object collections and action invocations.

When combined with Apache Isis' own xref:vro:ROOT:content-negotiation/apache-isis-v2-profile.adoc[simplified representations], these are pretty much all that is needed  for this use case.


The service is_not_ (currently) used by the framework itself; it is provided as a convenience for developers to build REST applications.


== See also

* xref:refguide:viewer:index/restfulobjects/rendering/service/swagger/SwaggerServiceMenu.adoc[SwaggerServiceMenu]
+
part of the xref:vro:ROOT:about.adoc[REST API (Restful Objects viewer)], this provides a prototype action that enables the swagger spec to be downloaded from theUI.

* xref:refguide:testing:index/integtestsupport/applib/swagger/SwaggerExporter.adoc[SwaggerExporter]
+
can be used to generate a Swagger spec, for example within a test suite or larger build pipeline.
+
An example of its use can be found in the demo app:
+
[source,java]
.SwaggerExport_IntegTest.java
----
@Import({
        IsisModuleViewerRestfulObjectsJaxrsResteasy4.class
})
class SwaggerExport_IntegTest extends ApplicationIntegTestAbstract {

    @Inject ServiceRegistry serviceRegistry;

    @Test
    void export() throws IOException {
        val swaggerExporter = new SwaggerExporter(serviceRegistry);
        swaggerExporter.export(Visibility.PRIVATE, Format.JSON);
    }
}
----
