Reputation: 588
Day before yesterday I came to know about swagger.Its fantastic.But may be because of my lack of knowledge there is something I am unable to do. I tried hard to solve it and finally I putting it as a question here.
my pom.xml
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-springmvc</artifactId>
<version>0.5.2</version>
</dependency>
I have added this dependency. my servlet-context.xml is as below.I did bind the swagger configuration bean and make this config configurations enabled.
<!-- Configuration Bean -->
<bean id="documentationConfig" class="com.mangofactory.swagger.configuration.DocumentationConfig"/>
<context:annotation-config />
<mvc:default-servlet-handler/>
Create the swagger.properties with the following entries.
documentation.services.version=1.0
documentation.services.basePath=http://localhost:8080/swagger
and include the same in myapplication context the way any other property files are included.
<context:property-placeholder location="classpath:/swagger.properties" />
my controller to document the api and its methods
@Controller
@Api(value="onlinestore", description="Operations pertaining to Online Store")
@RequestMapping(value="/onlinestore")
public class OnlineStoreController {
@Autowired
private IStoreFront storeFrontService;
@ApiOperation(value = "View the Specific info of the product")
@RequestMapping(value="/authorize/viewProduct/{productid}", method=RequestMethod.GET)
public ResponseEntity<Object> viewProduct(@ApiParam(name="productId", value="The Id of the product to be viewed", required=true)
Now by clicking the following link I am able to see the documenation
http://localhost:8080/swagger/api-docs
the result is as below
<ApiDocumentation>
<apiVersion>1.0</apiVersion>
<apis>
<description>Operations pertaining to Online Store</description>
<path>/api-docs/onlinestore</path>
</apis>
<basePath>http://localhost:8080/swagger</basePath>
<swaggerVersion>1.0</swaggerVersion>
</ApiDocumentation>
it returns xml format. Then I integrated the swagger UI using the following link https://github.com/swagger-api/swagger-ui
.
The index.html page is as below :
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Swagger UI</title>
<link rel="icon" type="image/png" href="images/favicon-32x32.png" sizes="32x32" />
<link rel="icon" type="image/png" href="images/favicon-16x16.png" sizes="16x16" />
<link href='css/typography.css' media='screen' rel='stylesheet' type='text/css'/>
<link href='css/reset.css' media='screen' rel='stylesheet' type='text/css'/>
<link href='css/screen.css' media='screen' rel='stylesheet' type='text/css'/>
<link href='css/reset.css' media='print' rel='stylesheet' type='text/css'/>
<link href='css/print.css' media='print' rel='stylesheet' type='text/css'/>
<script src='lib/jquery-1.8.0.min.js' type='text/javascript'></script>
<script src='lib/jquery.slideto.min.js' type='text/javascript'></script>
<script src='lib/jquery.wiggle.min.js' type='text/javascript'></script>
<script src='lib/jquery.ba-bbq.min.js' type='text/javascript'></script>
<script src='lib/handlebars-2.0.0.js' type='text/javascript'></script>
<script src='lib/js-yaml.min.js' type='text/javascript'></script>
<script src='lib/lodash.min.js' type='text/javascript'></script>
<script src='lib/backbone-min.js' type='text/javascript'></script>
<script src='swagger-ui.js' type='text/javascript'></script>
<script src='lib/highlight.9.1.0.pack.js' type='text/javascript'></script>
<script src='lib/highlight.9.1.0.pack_extended.js' type='text/javascript'></script>
<script src='lib/jsoneditor.min.js' type='text/javascript'></script>
<script src='lib/marked.js' type='text/javascript'></script>
<script src='lib/swagger-oauth.js' type='text/javascript'></script>
<!-- Some basic translations -->
<!-- <script src='lang/translator.js' type='text/javascript'></script> -->
<!-- <script src='lang/ru.js' type='text/javascript'></script> -->
<!-- <script src='lang/en.js' type='text/javascript'></script> -->
<script type="text/javascript">
$(function () {
var url = window.location.search.match(/url=([^&]+)/);
if (url && url.length > 1) {
url = decodeURIComponent(url[1]);
} else {
url = "http://localhost:8080/swagger/api-docs";
}
hljs.configure({
highlightSizeThreshold: 5000
});
// Pre load translate...
if(window.SwaggerTranslator) {
window.SwaggerTranslator.translate();
}
window.swaggerUi = new SwaggerUi({
url: url,
dom_id: "swagger-ui-container",
supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
onComplete: function(swaggerApi, swaggerUi){
if(typeof initOAuth == "function") {
initOAuth({
clientId: "your-client-id",
clientSecret: "your-client-secret-if-required",
realm: "your-realms",
appName: "your-app-name",
scopeSeparator: ",",
additionalQueryStringParams: {}
});
}
if(window.SwaggerTranslator) {
window.SwaggerTranslator.translate();
}
},
onFailure: function(data) {
log("Unable to Load SwaggerUI");
},
docExpansion: "none",
jsonEditor: false,
defaultModelRendering: 'schema',
showRequestHeaders: false
});
window.swaggerUi.load();
function log() {
if ('console' in window) {
console.log.apply(console, arguments);
}
}
});
</script>
</head>
<body class="swagger-section">
<div id='header'>
<div class="swagger-ui-wrap">
<a id="logo" href="http://swagger.io"><img class="logo__img" alt="swagger" height="30" width="30" src="images/logo_small.png" /><span class="logo__title">swagger</span></a>
<form id='api_selector'>
<div class='input'><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text"/></div>
<div id='auth_container'></div>
<div class='input'><a id="explore" class="header__btn" href="#" data-sw-translate>Explore</a></div>
</form>
</div>
</div>
<div id="message-bar" class="swagger-ui-wrap" data-sw-translate> </div>
<div id="swagger-ui-container" class="swagger-ui-wrap"></div>
</body>
</html>
Now the when I click this link http://localhost:8080/swagger/dist/index.html
I am getting as above. Clearly it tells me that it is expecting json but getting xml as input as http://localhost:8080/swagger/api-docs
is returning xml. It is axpecting something like this :
{ "ApiDocumentation": { "apiVersion": "1.0", "apis": { "description": "Operations pertaining to Online Store", "path": "/api-docs/onlinestore" }, "basePath": "http://localhost:8080/onlineStore", "swaggerVersion": "1.0" } }
I am unable to understand where did I went wrong.
Upvotes: 2
Views: 1177
Reputation: 6824
You need to first make sure that your server is configured to produce JSON:
curl -H Accept:application/json http://localhost:8080/swagger/api-docs
And if you don't get JSON back, you have a server configuration issue. If this shows JSON, it's possible that your server is expecting a different Accept header, like application/json;charset=UTF8
, in which case you can tell swagger-ui to send that instead of just application/json
:
window.swaggerUi = new SwaggerUi({
url: url,
swaggerRequestHeaders: 'application/json;charset=UTF8',
// ...
Upvotes: 0