简介

号称：世界最流行的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界面进行接口测试。

Swagger介绍-一套流行的API框架的相关教程结束。