Spring boot 整合Swagger

推荐一个博客,讲的不错

http://www.cnblogs.com/softidea/p/6251249.html

前言

引用:http://blog.csdn.net/wangnan9279/article/details/44541665
Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。如果想深入分析项目源码，了解更多内容，见参考资料。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

个人的学习及使用过程(最下边有完整的代码,过程是我的经验,可以省略不看)

• 1 学习
  在网上寻找好多的demo来学习,结果都无法达到自己的要求,这个出来了,然后这个又丢失了,真是丢了东墙失了西墙,总之就是没办法达到自己的要求,经过6个多小时的奋斗,终于整出来符合自己要求的东西了,下面我讲一下我的学习过程.
• 1.1 初学demo

pom 文件(这个pom文件没有出什么大问题,全局都使用这个pom)

<!-- Spring Boot 启动父依赖 核心模块，包括自动配置支持、日志和YAML-->    <parent>        <groupId>org.springframework.boot</groupId>        <artifactId>spring-boot-starter-parent</artifactId>        <version>1.5.1.RELEASE</version>    </parent>    <dependencies>        <!-- Spring Boot web依赖 -->        <dependency>            <groupId>org.springframework.boot</groupId>            <artifactId>spring-boot-starter-web</artifactId>        </dependency>        <!--SeaSwagger-->        <dependency>            <groupId>io.springfox</groupId>            <artifactId>springfox-swagger-ui</artifactId>            <version>2.2.2</version>        </dependency>        <dependency>            <groupId>io.springfox</groupId>            <artifactId>springfox-swagger2</artifactId>            <version>2.2.2</version>        </dependency>        <dependency>            <groupId>junit</groupId>            <artifactId>junit</artifactId>            <version>3.8.1</version>            <scope>test</scope>        </dependency>        <!-- 实现spring boot的热部署 -->        <dependency>            <!--Spring 官方提供的热部署插件 -->            <groupId>org.springframework.boot</groupId>            <artifactId>spring-boot-devtools</artifactId>            <optional>true</optional>        </dependency>    </dependencies>    <build>        <finalName>SpringBoot_Study</finalName>        <plugins>            <plugin>                <groupId>org.springframework.boot</groupId>                <artifactId>spring-boot-maven-plugin</artifactId>                <dependencies>                    <dependency>                        <groupId>org.springframework</groupId>                        <artifactId>springloaded</artifactId>                        <version>1.2.6.RELEASE</version>                    </dependency>                </dependencies>            </plugin>        </plugins>    </build>

启动类

import org.springframework.boot.SpringApplication;import org.springframework.boot.autoconfigure.SpringBootApplication;import springfox.documentation.swagger2.annotations.EnableSwagger2;@SpringBootApplication@EnableSwagger2 // 注意这个地方,其实是没用的,(原因不知道)public class SwaggerApplication {    public static void main(String[] args) {        SpringApplication.run(SwaggerApplication.class);    }}

测试使用的Controller(这个类也没变化,全局使用)

import io.swagger.annotations.Api;import io.swagger.annotations.ApiImplicitParam;import io.swagger.annotations.ApiOperation;import org.springframework.stereotype.Controller;import org.springframework.web.bind.annotation.RequestMapping;/** * @Api：用在类上，说明该类的作用 * @ApiOperation：用在方法上，说明方法的作用 * @ApiImplicitParams：用在方法上包含一组参数说明 * @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面 paramType：参数放在哪个地方 *              header-->请求参数的获取：@RequestHeader *              query-->请求参数的获取：@RequestParam *              path（用于restful接口）-->请求参数的获取：@PathVariable *              body（不常用） *              form（不常用） *              name：参数名 *              dataType：参数类型 *              required：参数是否必须传 *              value：参数的意思 *              defaultValue：参数的默认值 *              httpMethod:设置请求方式 * @ApiResponses：用于表示一组响应 * @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息 code：数字，例如400 *              message：信息，例如"请求参数没填好" *              response：抛出异常的类 * @ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候） * @ApiModelProperty：描述一个model的属性 */@Controller@Api("http相关接口")public class SwaggerDemoController {    @ApiOperation(value = "Swagger学习测试接口", notes = "根据url的id来指定删除用户",httpMethod = "POST")    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")    @RequestMapping("/swagger")    public String swaggerStudy() {        return "hello swagger";    }}

配置类(这个变化的很大)

import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.ComponentScan;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.service.ApiInfo;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;@EnableSwagger2 // 请注意这个地方public class SwaggerConfig {    @Bean    public Docket createRestApi() {        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo())                .select() // 这个地方以及下边三行                .apis(RequestHandlerSelectors.basePackage("com.qhong.web"))                .paths(PathSelectors.any())                .build();    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder()                .title("Spring Boot中使用Swagger2构建Restful Api")                .version("1.0")                .build();    }}

重点变化过程

我按照上边的配置类进行配置,然后启动了项目,结果想要的api接口说明出现了,但是我在配置类里面设置的title/version/等内容没有出现,继续变化

配置类二次变化

import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.ComponentScan;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.service.ApiInfo;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;@EnableSwagger2@Configuration // 这次变化的地方public class SwaggerConfig {    @Bean    public Docket createRestApi() {        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo())                .select()                .apis(RequestHandlerSelectors.basePackage("com.qhong.web"))                .paths(PathSelectors.any())                .build();    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder()                .title("Spring Boot中使用Swagger2构建Restful Api")                .version("1.0")                .build();    }}

看到代码中变化的地方了吧,添加上这个注解之后,结果还是不行,页面出现了配置类中的内容,但是api接口说明文档不见了,然后接着在变化

配置类三次变化

import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.ComponentScan;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.service.ApiInfo;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;@EnableSwagger2@Configuration public class SwaggerConfig {    @Bean    public Docket createRestApi() {        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo())                /*.select() // 变化的地方                .apis(RequestHandlerSelectors.basePackage("com.qhong.web"))                .paths(PathSelectors.any())                .build()*/;    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder()                .title("Spring Boot中使用Swagger2构建Restful Api")                .version("1.0")                .build();    }}

这次变化之后,好了,配置类的配置内容也出现了,接口说明文档也出现了,但是还有问题.

再次出现的问题

我按照现在好用的配置方式,原封不动的添加到我的项目中,结果swagger-ui.HTML页面无法访问了,在网上查,发现是因为我在application.properties文件中配置了spring.mvc.view.prefix和spring.mvc.view.suffix,然后访问swagger-ui.html就被影响到了,

解决方法

swagger的配置类继承WebMvcConfigurerAdapter,重写addResourceHandlers方法,具体的最终配置类如下:

import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.ComponentScan;import org.springframework.context.annotation.Configuration;import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.service.ApiInfo;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration@EnableSwagger2@ComponentScan("xx.xx.xx")public class SwaggerConfig extends WebMvcConfigurerAdapter {    /**     * 配置文件中配置了页面访问的相关信息,就需要有该方法,否则无法访问swagger-ui.html     * @param registry --     */    @Override    public void addResourceHandlers(ResourceHandlerRegistry registry) {        registry.addResourceHandler("swagger-ui.html")                .addResourceLocations("classpath:/META-INF/resources/");        registry.addResourceHandler("/webjars/**")                .addResourceLocations("classpath:/META-INF/resources/webjars/");    }    @Bean    public Docket createRestApi() {        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo());    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder()                .title("Spring Boot中使用Swagger2构建Restful Api")                .description("Spring boot Swagger2 study：Spring boot Swagger2 study")                .termsOfServiceUrl("Spring boot Swagger2 study")                .contact("qhong")                .version("1.0")                .build();    }}

还有最后的一处变化,是在启动类中

无意中发现的,启动类中不需要@EnableSwagger2这个注解

import org.springframework.boot.SpringApplication;import org.springframework.boot.autoconfigure.SpringBootApplication;@SpringBootApplicationpublic class SwaggerApplication {    public static void main(String[] args) {        SpringApplication.run(SwaggerApplication.class);    }}

最后贴出完整版的代码

POM文件

<!-- Spring Boot 启动父依赖 核心模块，包括自动配置支持、日志和YAML-->    <parent>        <groupId>org.springframework.boot</groupId>        <artifactId>spring-boot-starter-parent</artifactId>        <version>1.5.1.RELEASE</version>    </parent>    <dependencies>        <!-- Spring Boot web依赖 -->        <dependency>            <groupId>org.springframework.boot</groupId>            <artifactId>spring-boot-starter-web</artifactId>        </dependency>        <!--SeaSwagger-->        <dependency>            <groupId>io.springfox</groupId>            <artifactId>springfox-swagger-ui</artifactId>            <version>2.2.2</version>        </dependency>        <dependency>            <groupId>io.springfox</groupId>            <artifactId>springfox-swagger2</artifactId>            <version>2.2.2</version>        </dependency>        <dependency>            <groupId>junit</groupId>            <artifactId>junit</artifactId>            <version>3.8.1</version>            <scope>test</scope>        </dependency>        <!-- 实现spring boot的热部署 -->        <dependency>            <!--Spring 官方提供的热部署插件 -->            <groupId>org.springframework.boot</groupId>            <artifactId>spring-boot-devtools</artifactId>            <optional>true</optional>        </dependency>    </dependencies>    <build>        <finalName>SpringBoot_Study</finalName>        <plugins>            <plugin>                <groupId>org.springframework.boot</groupId>                <artifactId>spring-boot-maven-plugin</artifactId>                <dependencies>                    <dependency>                        <groupId>org.springframework</groupId>                        <artifactId>springloaded</artifactId>                        <version>1.2.6.RELEASE</version>                    </dependency>                </dependencies>            </plugin>        </plugins>    </build>

启动类

import org.springframework.boot.SpringApplication;import org.springframework.boot.autoconfigure.SpringBootApplication;import springfox.documentation.swagger2.annotations.EnableSwagger2;@SpringBootApplication@EnableSwagger2public class SwaggerApplication {    public static void main(String[] args) {        SpringApplication.run(SwaggerApplication.class);    }}

Controller层

import cn.zfs.swagger.model.User;import io.swagger.annotations.*;import org.springframework.web.bind.annotation.*;import java.util.ArrayList;import java.util.List;/** * @Api：用在类上，说明该类的作用 * @ApiOperation：用在方法上，说明方法的作用 * @ApiImplicitParams：用在方法上包含一组参数说明 * @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面 *              paramType：参数放在哪个地方 *                  header-->请求参数的获取：@RequestHeader *                  query-->请求参数的获取：@RequestParam *                  path（用于restful接口）-->请求参数的获取：@PathVariable *                  body（不常用） *                  form（不常用） *              name：参数名 *              dataType：参数类型 *              required：参数是否必须传 *              value：参数的意思 *              defaultValue：参数的默认值 *              httpMethod:设置请求方式 * @ApiResponses：用于表示一组响应 * @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息 code：数字，例如400 *              message：信息，例如"请求参数没填好" *              response：抛出异常的类 * @ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候） * @ApiModelProperty：描述一个model的属性 */@RestController@Api("http相关接口")public class SwaggerDemoController {    ArrayList<User> userList = new ArrayList<>();    @ApiOperation(value = "获取用户列表", notes = "获取用户列表--notes", produces = "application/json")    @ApiResponses(value = {            @ApiResponse(code = 405, message = "405 错误"), // 在默认Response的基础上增加新的Response说明            @ApiResponse(code = 404, message = "404 错误") // 覆盖404错误的说明    })    @ApiImplicitParam(name = "username", value = "用户名称", dataType = "string", paramType = "query") //描述接口参数    @RequestMapping(value = "/getuserlist", method = RequestMethod.POST)    public List<User> getUserList(String username) {        userList.add(new User("张三"));        userList.add(new User("李四"));        userList.add(new User("王五"));        if (!userList.contains(new User(username))) {            userList.add(new User(username + "(我不在顺序当中)"));        }        return userList;    }    @ApiOperation(value = "添加用户", notes = "添加用户--notes")    @ApiImplicitParams(value = { // 描述多个参数            @ApiImplicitParam(name = "username", value = "用户名称", paramType = "query", dataType = "String")    })    @RequestMapping(value = "/adduser", method = RequestMethod.POST)    public String addUser(String username) {        userList.add(new User(username));        return "更新成功";    }    /**     * 这种方式不是很好     *     * @param id     * @return     */    @ApiOperation(value = "根据id删除用户", notes = "根据id删除用户--notes", httpMethod = "POST")    @RequestMapping("/delUser")    public User delUser(@ApiParam(value = "用户ID", required = true) @RequestParam int id) {        User user = userList.remove(id);        return user;    }    /**     * 这种方式不行 kill     *     * @param id     * @return     */    @ApiOperation(value = "根据id删除用户.bak", httpMethod = "POST")    @ApiParam(value = "用户id", required = true)    @RequestMapping("/deluserBak")    public User deluserBak(int id) {        User user = userList.remove(id);        return user;    }    @ApiOperation(value = "添加用户",httpMethod = "POST")  /*  @ApiImplicitParams(value = {            @ApiImplicitParam(name = "username",required = true,value = "用户名称",paramType = "query")    })*/    @RequestMapping("/saveUser")    public List<User> saveuser(@ModelAttribute User user){        userList.add(user);        return userList;    }}

配置类

import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.ComponentScan;import org.springframework.context.annotation.Configuration;import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.service.ApiInfo;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;@Configuration@ComponentScan("cn.zfs") // 注意这里的包public class SwaggerConfig extends WebMvcConfigurerAdapter {    /**     * 如果你在配置文件中配置了页面访问的相关信息,就需要有该方法,否则无法访问swagger-ui.html     * @param registry --     */    @Override    public void addResourceHandlers(ResourceHandlerRegistry registry) {        registry.addResourceHandler("swagger-ui.html")                .addResourceLocations("classpath:/META-INF/resources/");        registry.addResourceHandler("/webjars/**")                .addResourceLocations("classpath:/META-INF/resources/webjars/");    }    @Bean    public Docket createRestApi() {        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo())                .select()                .apis(RequestHandlerSelectors.basePackage("cn.zfs"))// 注意这里的包                .paths(PathSelectors.any())                .build();    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder()                .title("Spring Boot中使用Swagger2构建Restful Api") //设置文档的标题                .description("Spring boot Swagger2 study：Spring boot Swagger2 study") //设置文档的描述->1.Overview                .termsOfServiceUrl("Spring boot Swagger2 study") //设置文档的License信息->1.3 License information                .contact("qhong")//设置文档的联系方式->1.2 Contact information                .version("1.0")                .build();    }}

swagger一些注解的简单解释

引用:http://www.cnblogs.com/java-zhao/p/5348113.html

/** * @Api：用在类上，说明该类的作用 * @ApiOperation：用在方法上，说明方法的作用 * @ApiImplicitParams：用在方法上包含一组参数说明 * @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面 *              paramType：参数放在哪个地方 *              header-->请求参数的获取：@RequestHeader *              query-->请求参数的获取：@RequestParam *              path（用于restful接口）-->请求参数的获取：@PathVariable *              body（不常用） *              form（不常用） *              name：参数名 *              dataType：参数类型 *              required：参数是否必须传 *              value：参数的意思 *              defaultValue：参数的默认值 *              httpMethod:设置请求方式 * @ApiResponses：用于表示一组响应 * @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息 code：数字，例如400 *              message：信息，例如"请求参数没填好" *              response：抛出异常的类 * @ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候） * @ApiModelProperty：描述一个model的属性 */

model对象

import io.swagger.annotations.ApiModel;import io.swagger.annotations.ApiModelProperty;@ApiModel(value = "User",discriminator = "用户")public class User {    public User() {    }    public User(String username) {        this.username = username;    }    @ApiModelProperty(name = "username",value = "姓名")    private String username;    public String getUsername() {        return username;    }    public void setUsername(String username) {        this.username = username;    }}