swagger集成到SpringMVC項目中

pom.xml

<!-- Swagger -->  
<dependency>  
    <groupId>io.swagger</groupId>  
    <artifactId>swagger-core</artifactId>  <!--swagger核心代碼-->
    <version>1.5.8</version>  
</dependency>  
<dependency>  
    <groupId>io.springfox</groupId>  
    <artifactId>springfox-swagger2</artifactId>  <!--swagger和該框架的集成-->
    <version>2.4.0</version>  
</dependency>  
<dependency>  
    <groupId>io.springfox</groupId>  
    <artifactId>springfox-swagger-ui</artifactId>  <!--swagger-ui和和swagger-ui的集成>
    <version>2.4.0</version>  
</dependency>  

當JAR包添加成功後，在項目中會出現如下系列JAR包：

SwaggerConfiguration.java

@Configuration  
@EnableSwagger2  
public class SwaggerConfiguration {  
    @Bean  
    public Docket api() {  
        return new Docket(DocumentationType.SWAGGER_2)  
                .select()  
                .apis(RequestHandlerSelectors.any())  
                .paths(PathSelectors.any())  
                .build();  
    }  
}  

SwaggerWebMvcConfigurerAdapter.java

@Configuration  
@EnableWebMvc  
@ComponentScan(basePackages = "com.xx.travel.csc.stat.controller")  
public class SwaggerWebMvcConfigurerAdapter extends WebMvcConfigurerAdapter {  
   
    @Bean  
    public ViewResolver viewResolver() {  
        InternalResourceViewResolver viewResolver = new InternalResourceViewResolver();  
        viewResolver.setViewClass(JstlView.class);  
        viewResolver.setPrefix("/WEB-INF/views/");  
        viewResolver.setSuffix(".jsp");  
        return viewResolver;  
    }  
   
    @Bean  
    public MessageSource messageSource() {  
        ResourceBundleMessageSource messageSource = new ResourceBundleMessageSource();  
        messageSource.setBasename("messages");  
        return messageSource;  
    }  
    @Override  
    public void addResourceHandlers(ResourceHandlerRegistry registry) {  
        super.addResourceHandlers(registry);  
        registry.addResourceHandler("swagger-ui.html")  
                .addResourceLocations("classpath:/META-INF/resources/");  
        registry.addResourceHandler("/webjars/**")  
                .addResourceLocations("classpath:/META-INF/resources/webjars/");  
    }  
    @Override  
    public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {  
        configurer.enable();  
    }  
}  

Controller實例中的應用

只要在我們的Controller裏面增加註解 ApiOperation和ApiParam 即可。然後再swagger-ui界面就能看到我們相關api的描述！

@Controller  
@RequestMapping(value = "/stat")  
public class SwaggerController {  
       
    @ResponseBody  
    @RequestMapping(value = "/helloworld", method = RequestMethod.GET)  
    @ApiOperation(nickname = "swagger-helloworld", value = "Swagger的世界", notes = "測試HelloWorld")  
    public String helloWorld(@ApiParam(value = "暱稱") @RequestParam String nickname) {  
        return "Hello world, " + nickname;  
    }  
       
    @ResponseBody  
    @RequestMapping(value = "/objectio", method = RequestMethod.POST)  
    @ApiOperation(nickname = "swagger-objectio", value = "Swagger的ObjectIO", notes = "測試對象輸入輸出")  
    public SwaggerOutput objectIo(@ApiParam(value = "輸入") @RequestBody SwaggerInput input) {  
        SwaggerOutput output = new SwaggerOutput();  
        output.setId(input.getId());  
        output.setName("Swagger");  
        return output;  
    }  
}  

與上面註解對應的ui界面顯示

Web界面

啓動項目，輸入Http://{Path}/swagger-ui.html，就可以給前端展示相關的API文檔，並像使用Postman以及Curl命令一樣，通過Web界面進行接口測試。

別人的一個集成實例地址：

在有些項目中spring mvc的請求是以某一後綴（url-pattern, 例如 .do）結尾的, 這樣就要做一些必要的修改，在swagger-ui.js中，修改如下

 opts.responseContentType = $('div select[name=responseContentType]', $(this.el)).val();
      opts.requestContentType = $('div select[name=parameterContentType]', $(this.el)).val();
      $('.response_throbber', $(this.el)).show();

      // here, add suffix
      var suffix = ".do";
      if (!this.model.path.endsWith(suffix)) {
          this.model.path = this.model.path + suffix;
      }

      if (isFileUpload) {
        $('.request_url', $(this.el)).html('<pre></pre>');
        $('.request_url pre', $(this.el)).text(this.invocationUrl);

        opts.useJQuery = true;
        map.parameterContentType = 'multipart/form-data';
        this.map = map;
        return this.model.execute(map, opts, this.showCompleteStatus, this.showErrorStatus, this);
      } else {
        this.map = map;
        return this.model.execute(map, opts, this.showCompleteStatus, this.showErrorStatus, this);
      }

別人的一個集成實例地址：https://github.com/pumadong/cl-roadshow/tree/master/roadshow-swagger