Springboot+swagger2.7集成开发

本篇文章是介绍最新的springboot和swagger2.7集成开发和2.0稍微有一些出入：

Springboot集成环境配置
Swagger2.7集成
集成测试

Springboot集成环境配置

Spring Boot是由Pivotal团队提供的全新框架，其设计目的是用来简化新Spring应用的初始搭建以及开发过程。该框架使用了特定的方式来进行配置，从而使开发人员不再需要定义样板化的配置。通过这种方式，Boot致力于在蓬勃发展的快速应用开发领域（rapid application development）成为领导者。 —— [ INFO深入学习]

代码块

开发Spring Boot应用，例如：

@RestController

class App {

  @RequestMapping("/")

  String home() {

    "hello"

  }

}

引入SpringBoot的JAR文件.

<parent>

    <groupId>org.springframework.boot</groupId>

    <artifactId>spring-boot-starter-parent</artifactId>

    <version>1.2.7.RELEASE</version>

</parent>

<dependencies>

    <dependency>

        <groupId>org.springframework.boot</groupId>

        <artifactId>spring-boot-starter-web</artifactId>

    </dependency>

<dependency>

    <groupId>org.springframework.boot</groupId>

    <artifactId>spring-boot-starter-test</artifactId>

    <scope>test</scope>

</dependency>

<dependency>

    <groupId>org.springframework.boot</groupId>

    <artifactId>spring-boot-starter-jdbc</artifactId>

</dependency>



编制Main.java

import org.springframework.boot.autoconfigure.EnableAutoConfiguration;

import org.springframework.web.bind.annotation.PathVariable;

import org.springframework.web.bind.annotation.RequestMapping;

import org.springframework.web.bind.annotation.RestController;  

@RestController

@EnableAutoConfiguration

public class Example {  

    @RequestMapping("/")

    String index() {

        return "Hello World!";

    }  

    @RequestMapping("/index/{sayHello}")

    String index(@PathVariable String sayHello) {

        return "Hello "+sayHello+"!!!";

    }

}


编写application.properties

application.hellowmsg=Hello World

server.port=8081 #端口

logging.level.=INFO

编制Application.java

@EnableScheduling

@EnableTransactionManagement

@SpringBootApplication

public class App extends WebMvcConfigurerAdapter {

    public static void main(String[] args) throws Exception {

        SpringApplication app = new SpringApplication(App.class);

        app.setWebEnvironment(true);

        app.setShowBanner(false);

        Set<Object> set = new HashSet<Object>();

        // set.add("classpath:applicationContext.xml");

        app.setSources(set);

        app.run(args);

    }

运行Application.java
看到

2017-11-15 16:14:08.391  INFO 12524 --- [           main] s.d.s.w.s.ApiListingReferenceScanner     : Scanning for api listing references

2017-11-15 16:14:08.607  INFO 12524 --- [           main] s.b.c.e.t.TomcatEmbeddedServletContainer : Tomcat started on port(s): 8081 (http)

并没有出错，表示成功，直接访问http://localhost:8081/,输出Hello World!

Swagger2.7集成

加入maven的仓库文件

<!--swagger2 integration -->

    <dependency>

        <groupId>io.springfox</groupId>

        <artifactId>springfox-swagger2</artifactId>

        <version>2.7.0</version>

    </dependency>

    <dependency>

        <groupId>io.springfox</groupId>

        <artifactId>springfox-swagger-ui</artifactId>

        <version>2.7.0</version>

    </dependency>

创建SwaggerConfig的配置文件

import static com.google.common.collect.Lists.newArrayList;

import java.util.List;

import org.springframework.beans.factory.annotation.Autowired;

import org.springframework.beans.factory.annotation.Value;

import org.springframework.boot.context.properties.ConfigurationProperties;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import com.fasterxml.classmate.TypeResolver;

import springfox.documentation.builders.ApiInfoBuilder;

import springfox.documentation.builders.PathSelectors;

import springfox.documentation.builders.RequestHandlerSelectors;

import springfox.documentation.service.ApiInfo;

import springfox.documentation.service.ApiKey;

import springfox.documentation.service.AuthorizationScope;

import springfox.documentation.service.SecurityReference;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spi.service.contexts.SecurityContext;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration

@EnableSwagger2

@ConfigurationProperties

public class SwaggerConfig {

    @Value("${swagger.version}")

    private String version;

    @Autowired

    private TypeResolver typeResolver;

    @Bean

    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage("com.hp.ctrl"))

                .paths(PathSelectors.any()).build().apiInfo(apiInfo());

    }

    private ApiInfo apiInfo() {

        return new ApiInfoBuilder().title("构建RESTful APIs").description("更多请关注：http://my.csdn.net/elvishehai")

                .license("The Apache License, Version 2.0")

                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html").termsOfServiceUrl("http://my.csdn.net/elvishehai")

                .version(version).build();

    }

}

下一步写REST的COTR

@Api(value = "API - SMSController")

@RestController

public class SmsController {

@ApiOperation(value = "测试服务", notes = "测试服务")

    @ApiImplicitParam(name = "smsRequestBean", value = "用户详细实体SmsRequestBean", required = true, dataType = "SmsRequestBean")

    @RequestMapping(value = "/post", method = RequestMethod.POST)

    public String post(@RequestBody SmsRequestBean smsRequestBean) {

        return "服务测试成功，你输入的参数为：" + smsRequestBean.getApplicationId();

    }

    @ApiOperation(value = "测试服务", notes = "测试服务", consumes = "application/json", produces = "application/json")

    @RequestMapping(value = "/test/{input}", method = RequestMethod.GET)

    @ResponseBody

    public String getUser(@PathVariable("input") String input) {

        return "服务测试成功，你输入的参数为：" + input;

    }

}

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。
@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiParamImplicitL：一个请求参数
@ApiParamsImplicit 多个请求参数

运行application.java
在浏览器上输入http://localhost:8081/swagger-ui.html

可以看到上面，测试就成功。
在上图请求的页面中，我们看到user的Value是个输入框？是的，Swagger除了查看接口功能外，还提供了调试测试功能，我们可以点击上图中右侧的Model Schema（黄色区域：它指明了User的数据结构），此时Value中就有了user对象的模板，我们只需要稍适修改，点击下方“Try it out！”按钮，即可完成了一次请求调用！
此时，你也可以通过几个GET请求来验证之前的POST请求是否正确。
相比为这些接口编写文档的工作，我们增加的配置内容是非常少而且精简的，对于原有代码的侵入也在忍受范围之内。因此，在构建RESTful API的同时，加入swagger来对API文档进行管理，是个不错的选择。

+参考信息
http://swagger.io/ Swagger官方网站