Swagger介紹-一套流行的API框架

簡介

 

號稱：世界最流行的API框架

官網：http://swagger.io/

解決什么問題：在前后台分離的開發模式中，減小接口定義溝通成本，方便開發過程中測試，自動生成接口文檔。

實例代碼位置：https://github.com/pumadong/cl-roadshow/tree/master/roadshow-swagger

 

swagger使用方式

 

第一種

定義YAML文件，然后可以生成各種語言的代碼框架，對於后台程序員來說，較少人會願意寫出一堆YAML格式。

第二種

swagger有各種語言的插件，可以通過配置及少量代碼，生成接口文檔及測試界面。

我們多做了：一次性的配置及少量注解代碼。

我們不用再做：1、到Wiki中更新接口文檔；2、Postman形式的測試；3、Curl形式的測試

 

swagger java使用介紹

 

對於一個SpringMVC項目，使用swagger的配置如下：

pom.xml

 

<!-- Swagger -->
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-core</artifactId>
    <version>1.5.8</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.4.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.4.0</version>
</dependency>

 

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 即可。

 

@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;
    }
}

 

Web界面

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

 

 http://blog.csdn.net/puma_dong/article/details/51752099