---
slug: openapi
title: Open API
---
::: info
When using ASP.NET Core **Endpoint Routing** refer to [ASP.NET Core Swashbuckle Open API v3](/openapi) instead
:::
[Open API](https://www.openapis.org/) is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services. ServiceStack implements the
[OpenAPI Spec](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) back-end and embeds the Swagger UI front-end in a separate plugin which is available under [OpenAPI NuGet package](http://nuget.org/packages/ServiceStack.Api.OpenApi/):
:::copy
``
:::
## Installation
You can enable Open API by registering the `OpenApiFeature` plugin in AppHost with:
```csharp
public override void Configure(Container container)
{
...
Plugins.Add(new OpenApiFeature());
// Uncomment CORS feature if it needs to be accessible from external sites
// Plugins.Add(new CorsFeature());
...
}
```
Then you will be able to view the Swagger UI from `/swagger-ui/`. A link to **Swagger UI** will also be available from your `/metadata` [Metadata Page](/metadata-page).
## Open API Attributes
Each route could have a separate summary and description. You can set it with `Route` attribute:
```csharp
[Route("/hello", Summary = @"Default hello service.",
Notes = "Longer description for hello service.")]
```
You can set specific description for each HTTP method like shown below:
```csharp
[Route("/hello/{Name}", "GET", Summary="Says 'Hello' to provided Name",
Notes = "Longer description of the GET method which says 'Hello'")]
[Route("/hello/{Name}", "POST", Summary="Says 'Hello' to provided Name",
Notes = "Longer description of the POST method which says 'Hello'")]
```
You can also document your services in the OpenAPI with the new `[Api]` and `[ApiMember]` annotation attributes, e,g: Here's an example of a fully documented service:
```csharp
[Api("Service Description")]
[Tag("Core Requests")]
[ApiResponse(HttpStatusCode.BadRequest, "Your request was not understood")]
[ApiResponse(HttpStatusCode.InternalServerError, "Oops, something broke")]
[Route("/swagger/{Name}", "GET", Summary = "GET Summary", Notes = "Notes")]
[Route("/swagger/{Name}", "POST", Summary = "POST Summary", Notes="Notes")]
public class MyRequestDto
{
[ApiMember(Name="Name", Description = "Name Description",
ParameterType = "path", DataType = "string", IsRequired = true)]
[ApiAllowableValues("Name", typeof(Color))] //Enum
public string Name { get; set; }
}
```
Please note, that if you used `ApiMember.DataType` for annotating `OpenApiFeature` then you need to change the types to OpenAPI type when migrating to `OpenApiFeature`. For example, annotation of
```csharp
[ApiMember(DataType="int")]
```
need to be changed to
```csharp
[ApiMember(DataType="integer", Format="int32")]
```
Here is the table for type migration
| Swagger Type (DataType) | OpenAPI Type (DataType) | OpenAPI Format (Format) |
|-------------------------|-------------------------|-----------------------------|
| Array | array | |
| boolean | boolean | |
| byte | integer | int |
| Date | string | date |
| | string | date-time |
| double | number | double |
| float | number | float |
| int | integer | int32 |
| long | integer | int64 |
| string | string | |
You can use `[ApiAllowableValues]` lets you anotate enum properties as well as a restriction for values in array, e.g:
```csharp
[ApiAllowableValues("Includes", Values = new string[] { "Genres", "Releases", "Contributors" })]
public string[] Includes { get; set; }
```
::: info
The use of `ApiMember` turns your DTO properties as **opt-in only** for OpenApi metadata.
Meaning that only properties annotated with `[ApiMember]` will be included in the OpenApi metadata for classes
that use `[ApiMember]` on any of its properties.
:::
### Group APIs with Tags
You can tag the DTO with `[Tag]` attribute. Attributes are annotated by the same tag are grouped by the tag name in Swagger UI. DTOs can have multiple tags, e.g:
```csharp
[Tag("Core Features")]
[Tag("Scheduler")]
public class MyRequest { ... }
```
You can Exclude **properties** from being listed in OpenAPI with:
```csharp
[IgnoreDataMember]
```
Exclude **properties** from being listed in OpenAPI Schema Body with:
```csharp
[ApiMember(ExcludeInSchema=true)]
```
### Exclude Services from Metadata Pages
To exclude entire Services from showing up in OpenAPI or any other Metadata Services (i.e. Metadata Pages, Postman, NativeTypes, etc), annotate **Request DTO's** with:
```csharp
[ExcludeMetadata]
public class MyRequestDto { ... }
```
### Operation filters
You can override operation or parameter definitions by specifying the appropriate filter in plugin configuration:
```csharp
Plugins.Add(new OpenApiFeature
{
OperationFilter = (verb, operation) => operation.Tags.Add("all operations")
});
```
Available configuration options:
- `ApiDeclarationFilter` - allows to modify final result of returned OpenAPI json
- `OperationFilter` - allows to modify operations
- `SchemaFilter` - allows to modify OpenAPI schema for user types
- `SchemaPropertyFilter` - allows to modify propery declarations in OpenAPI schema
### Properties naming conventions
You can control naming conventions of generated properties by following configuration options:
- `UseCamelCaseSchemaPropertyNames` - generate camel case property names
- `UseLowercaseUnderscoreSchemaPropertyNames` - generate underscored lower cased property names (to enable this feature `UseCamelCaseModelPropertyNames` must also be set)
Example:
```csharp
Plugins.Add(new OpenApiFeature
{
UseCamelCaseSchemaPropertyNames = true,
UseLowercaseUnderscoreSchemaPropertyNames = true
});
```
### Change default Verbs
If left unspecified, the `[Route]` attribute allows Services to be called from any HTTP Verb which by default
are listed in the Open API specification under the most popular HTTP Verbs, namely `GET`, `POST`, `PUT` and `DELETE`.
This can be modified with `AnyRouteVerbs` which will let you specify which Verbs should be generated
for **ANY** Routes with unspecified verbs, e.g. we can restrict it to only emit routes for `GET` and `POST` Verbs with:
```csharp
Plugins.Add(new OpenApiFeature
{
AnyRouteVerbs = new List { HttpMethods.Get, HttpMethods.Post }
});
```
### Miscellaneous configuration options
- `DisableAutoDtoInBodyParam` - disables adding `body` parameter for Request DTO to operations
- `LogoUrl` - url of the logo image for Swagger UI
Example:
```csharp
Plugins.Add(new OpenApiFeature
{
DisableAutoDtoInBodyParam = true
});
```
## Virtual File System
The docs on the Virtual File System shows how to override embedded resources:
### Overriding OpenAPI Embedded Resources
ServiceStack's [Virtual File System](/virtual-file-system) supports multiple file source locations where you can override OpenAPI's embedded files by including your own custom files in the same location as the existing embedded files. This lets you replace built-in ServiceStack embedded resources with your own by simply copying the [/swagger-ui](https://github.com/ServiceStack/ServiceStack/tree/master/src/ServiceStack.Api.OpenApi/swagger-ui) files you want to customize and placing them in your Website Directory at:
```
/swagger-ui
/css
/fonts
/images
/lang
/lib
index.html
swagger-ui.js
```
#### Injecting custom JavaScript
As part of the customization you can add custom `patch.js` and `patch-preload.js`:
```
/swagger-ui
patch.js
patch-preload.js
```
which will be injected in the `/swagger-ui` index page, `patch-preload.js` is embedded before `swaggerUi.load()` is called:
```js
// contents of patch-preload.js
window.swaggerUi.load();
```
So you can use it to customize the `swaggerUi` configuration object before it's loaded, whilst `patch.js` is embedded just before the end of the `` tag, e.g:
```html