I'm using NSwag and trying to convert an OpenAPI JSON document to version 2. This is my configuration:
public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
services.AddOpenApiDocument(config =>
{
config.PostProcess = doc =>
{
doc.SchemaType = NJsonSchema.SchemaType.Swagger2;
}
}
}
However, when I paste the generated OpenAPI file into Swagger Editor, it shows errors:
How to configure NSwag to generate a proper OpenAPI 2.0 file?
To configure NSwag to output an OpenAPI 2.0 definition instead of OpenAPI 3.0, use .AddSwaggerDocument(...) instead of .AddOpenAPIDocument(...). More info:
https://github.com/RicoSuter/NSwag/wiki/AspNetCore-Middleware
Related
I have a springboot application and I want to convert to Micronaut, but how I config the openapi via code, like in this article
https://keepgrowing.in/java/springboot/how-to-secure-spring-boot-swagger-ui-with-basic-authentication/
Code snippet:
#Configuration
public class OpenApiConfig {
#Bean
public OpenAPI customOpenAPI(OpenApiProperties properties) {
var openApi = new OpenAPI()
.info(getInfo(properties));
return openApi;
}
private Info getInfo(OpenApiProperties properties) {
return new Info()
.title(properties.getProjectTitle())
.description(properties.getProjectDescription())
.version(properties.getProjectVersion())
.license(getLicense());
}
private License getLicense() {
return new License()
.name("Unlicense")
.url("https://unlicense.org/");
}
}
Currently, I have already done the ff:
Replace #Bean as #Singleton, Failed
Adding #Factory to the class, Failed
** The application compiles, but on run time the OpenApi definition is not set on the swagger ui
Micronaut generates the Open-API definition at the compilation time, so it's not possible to have dynamic properties. The only way is to set those values is to use annotations https://micronaut-projects.github.io/micronaut-openapi/latest/guide/index.html
I am trying to port a Swagger UI from Springfox to Springdoc.
The Swagger UI is generated via Maven plugin
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
... from two different OpenAPI specifications, both implemented in the same Spring Boot application. We use two different specs for two different clients.
So far, my Swagger UI looked like this with Springfox. Note the drop-down list that allows to choose the spec to display.
Now, with Springdoc 1.6.6, the Swagger-UI looks like this.
Note that:
The default landing page is the sample Pet Store and none of my specifications, although I specified in my Spring Boot's application.yaml:
springdoc:
swagger-ui:
disable-swagger-default-url: true
No drop-down
I have to manually enter my specification's name into the "Explore" text field in order to see its Swagger UI
I tried addressing the missing drop-down by following I have installed OpenAPI 3 using springdoc, but the URL is strange. Can I change it to the expected value?, which claims to display a drop-down, but to no avail.
My questions:
How do I display the drop-down? Does Springdoc support it at all out-of-the-box?
Apparently, accessing http://localhost:8080/swagger-ui/index.html?urls.primaryName=Information makes the drop-down list of specs magically appear.
How do I make sure that the default URL http://localhost:8080/swagger-ui/index.html lands on one of my specs, and not on the Pet Store?
Here is btw. my Bean configuration:
#Configuration
public class SwaggerDocumentationConfig {
/**
* Path of the OpenAPI package extracted out of a random class in that package
*/
private static final String INFORMATION_PACKAGE = InformationApi.class.getPackageName();
/**
* Path of the OpenAPI package extracted out of a random class in that package
*/
private static final String OPERATIONS_PACKAGE = OperationsApi.class.getPackageName();
private GroupedOpenApi getBaseApiDoc(String groupName, String packagePath) {
return GroupedOpenApi.builder()
.group(groupName)
.packagesToScan(packagePath)
.build();
}
#Bean
public GroupedOpenApi getOperationsApiDoc() {
return getBaseApiDoc("Operations", OPERATIONS_PACKAGE);
}
#Bean
public GroupedOpenApi getInfoApiDoc() {
return getBaseApiDoc("Information", INFORMATION_PACKAGE);
}
#Bean
public OpenAPI springShopOpenAPI() {
return new OpenAPI()
.info(new Info().title("SpringShop API")
.description("Spring shop sample application")
.version("v0.0.1")
.license(new License().name("Apache 2.0").url("http://springdoc.org")))
.externalDocs(new ExternalDocumentation()
.description("SpringShop Wiki Documentation")
.url("https://springshop.wiki.github.org/docs"));
}}
I have an application which provides an API with JAX-RS (Java API for RESTful Web Services / JSR-311).
For documentation purposes I provide an URL according to the OpenAPI-Specification, which is generated by Eclipse MicroProfile OpenAPI.
Everything is working fine, except the descriptions of the methods and parameters, which I need to add twice - in annotations and in JavaDoc:
/**
* Finds all resources with the given prefix.
*
* #param prefix
* the prefix of the resource
* #return the resources that start with the prefix
*/
#GET
#Path("/find/{prefix}")
#Produces(MediaType.APPLICATION_JSON)
#Operation(description = "Finds all resources with the given prefix")
public List<Resource> find(
#Parameter(description = "The prefix of the resource")
#PathParam("prefix") final String prefix) {
...
}
I know that no runtime library can read the JavaDoc (because it is not part of the class files), which is the main reason for the annotations. But I wonder if there is some other option for one of the OpenAPI generation tools (Swagger, Eclipse MicroProfile OpenAPI, ...), which prevents me from manually syncing the documentation?
In another project for example I'm using a doclet which serializes the JavaDoc and stores it in the class path, to present an Beans API documentation to the user at runtime. But even if I make use of this doclet here, I see no option to provide that JavaDoc descriptions to the OpenAPI libraries during runtime.
I know that I could drop the JavaDoc, if the users of my API use only "foreign languages", as they wouldn't see the JavaDoc anyway. But what happens if the other side of the API is a JAX-RS client? In that case the JavaDoc would be a huge support.
I got it running with Eclipse Microprofile OpenAPI.
I had to define my own OASFilter:
public class JavadocOASDescriptionFilter implements OASFilter {
#Override
public void filterOpenAPI(final OpenAPI openAPI) {
openAPI.getComponents().getSchemas().forEach(this::initializeSchema);
openAPI.getPaths().forEach(this::initializePathItem);
}
private void initializeSchema(final String name, final Schema schema) {
final SerializedJavadoc javadoc = findJavadocForSchema(name);
if (StringUtils.isEmpty(schema.getDescription())) {
schema.setDescription(javadoc.getTypeComment());
}
if (schema.getProperties() != null) {
schema.getProperties().forEach((property, propertySchema) -> {
if (StringUtils.isEmpty(propertySchema.getDescription())) {
propertySchema.setDescription(javadoc.getAttributeComments().get(property));
}
});
}
}
...
}
Then I had to declare that filter in META-INF/microprofile-config.properties:
mp.openapi.filter=mypackage.JavadocOASDescriptionReader
See here for the discussion on this topic: https://github.com/eclipse/microprofile-open-api/issues/485
How do I define basic authentication using Swagger 2.0 annotations and have it display in swagger UI.
In the resource I have:
#ApiOperation(value = "Return list of categories", response=Category.class, responseContainer="List", httpMethod="GET", authorizations = {#Authorization(value="basicAuth")})
public Response getCategories();
I looked here:
https://github.com/swagger-api/swagger-core/wiki/Annotations#authorization-authorizationscope
And it says "Once you've declared and configured which authorization schemes you support in your API, you can use these annotation to note which authorization scheme is required on a resource or a specific operation" But I can't find anything that talks about where to declare and configure the authorization schemes.
Update:
I found code on how to declare the schema, but I still do not see any information about the authentication schema in the UI. I'm not sure what I am missing
#SwaggerDefinition
public class MyApiDefinition implements ReaderListener {
public static final String BASIC_AUTH_SCHEME = "basicAuth";
#Override
public void beforeScan(Reader reader, Swagger swagger) {
}
#Override
public void afterScan(Reader reader, Swagger swagger) {
BasicAuthDefinition basicAuthDefinition = new BasicAuthDefinition();
swagger.addSecurityDefinition(BASIC_AUTH_SCHEME, basicAuthDefinition);
}
}
Using Springfox 2.6 annotations, you must first define Basic authentication as one of the security schemes when you set up the Docket in your configuration, like this:
List<SecurityScheme> schemeList = new ArrayList<>();
schemeList.add(new BasicAuth("basicAuth"));
return new
Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo)
.securitySchemes(schemeList)
...
Then you can use the Springfox annotations in your service to set Basic Auth for the operation for which you want to require authentication:
#ApiOperation(value = "Return list of categories", response=Category.class, responseContainer="List", httpMethod="GET", authorizations = {#Authorization(value="basicAuth")})
public Response getCategories();
I struggeled with this as well. In my case i used the swagger-maven-plugin. To solve this i added this within the maven plugin:
<securityDefinitions>
<securityDefinition>
<name>basicAuth</name>
<type>basic</type>
</securityDefinition>
</securityDefinitions>
After that i was able to add it on my resource like this:
#Api(value = "My REST Interface", authorizations = {#Authorization(value="basicAuth")})
The generated json included the security element for each endpoint:
"security":[{
"basicAuth" : []
}]
And the security definition:
"securityDefinitions" : {
"basicAuth" : {
"type" : "basic"
}
}
I hope this helps others as well.
You can use the #SwaggerDefinition
http://swagger.io/customizing-your-auto-generated-swagger-definitions-in-1-5-x/
or you can configure the swagger object directly, here's an example
http://www.programcreek.com/java-api-examples/index.php?source_dir=rakam-master/rakam/src/main/java/org/rakam/WebServiceRecipe.java
I have the latest dropwizard setup. Now I have created a simple API and I am trying to add Swagger on top. There is a Swagger implementation for dropwizard but the sample code is against Yammer dropwizard 0.6.2 which requires addProvider and addResource. The io.dropwizard environment doesn't seem to have this function. Can you please let me know how I can do this under io.dropwizard?
For Dropwizard 0.7.0 I configure swagger like this:
void configureSwagger(Environment environment) {
environment.jersey().register(new ApiListingResourceJSON());
environment.jersey().register(new ApiDeclarationProvider());
environment.jersey().register(new ResourceListingProvider());
ScannerFactory.setScanner(new DefaultJaxrsScanner());
ClassReaders.setReader(new DefaultJaxrsApiReader());
SwaggerConfig config = ConfigFactory.config();
config.setApiVersion(API_VERSION);
config.setBasePath(".." + environment.getApplicationContext().getContextPath());
}
EDIT
To run Swagger UI with Dropwizard clone the repo and copy the dist directory into src/main/resources/swagger/ (customizing as necessary). Then add the asset bundle like this:
#Override
public void initialize(Bootstrap<ApplicationConfiguration> bootstrap) {
bootstrap.addBundle(new AssetsBundle("/swagger/", "/docs", "index.html"));
}
There are some changes for Swagger spec 2.0 that you can see here:
https://github.com/swagger-api/swagger-core/tree/develop_2.0/samples/java-dropwizard
Namely the configuration is slightly different:
#Override
public void run(SwaggerSampleConfiguration configuration, Environment environment) {
environment.jersey().register(new ApiListingResource());
// specific to the sample
environment.jersey().register(new PetResource());
environment.getObjectMapper().setSerializationInclusion(JsonInclude.Include.NON_NULL);
BeanConfig config = new BeanConfig();
// api specific configuration
config.setTitle("Swagger sample app");
config.setVersion("1.0.0");
config.setResourcePackage("com.wordnik.swagger.sample");
config.setScan(true);
}
Dropwizard 1.0.2, Swagger 1.5.0. Call this from your application's run().
private void configureSwagger(Environment environment) {
BeanConfig magicBean = new BeanConfig();
magicBean.setVersion("0.1");
magicBean.setTitle("title");
magicBean.setBasePath("/api");
magicBean.setResourcePackage("com.me.resources");
magicBean.setScan(true);
environment.jersey().register(new ApiListingResourceJSON());
environment.jersey().register(new SwaggerSerializers());
}
In addition to what #fehguy messaged above, I would like to add on how to actually get the base path in dropwizard as well (atleast with 0.8) because apparently you will not be able to get basePath from the yml like this :
config.setBasePath(".." + environment.getApplicationContext().getContextPath());
You will have to do do something like this:
DefaultServerFactory defaultServerFactory = (DefaultServerFactory) serverConfiguration.getServerFactory();
String basePath = defaultServerFactory.getApplicationContextPath();
Refer to the github issue here which took me DAYS to figure out. Hope this helps others