关于swagger的使用

Swagger 是什么

简单说明一下，Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务的接口文档。

---

如何使用

1.pom
swagger 的版本需要十分小心，最新版本一方面需要依赖com.google.guava包，guava包又会由新的冲突，很麻烦，另一方面，与安全框架（Shiro，SpringSecurity）整合也可能会出问题，

因此，在这里挑选了一个比较稳定的版本 2.7.0

      <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>

---

2.configuration

package com.how2j.copy.config;

import org.springframework.context.annotation.Bean;
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;
@Configuration

public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.test.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("简单优雅的restfun风格")
                .termsOfServiceUrl("http://blog.csdn.net/")
                .version("1.0")
                .build();
    }
}

---

3.注解

    @ApiOperation(value = "主界面" , notes = "显示所有的教程")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id" ,value = "当前分类的教程" , required = false , dataType = "Integer" )
    })

@Api： 描述 Controller
@ApiIgnore： 忽略该 Controller，指不对当前类做扫描
@ApiOperation： 描述 Controller类中的 method接口
@ApiParam： 单个参数描述，与 @ApiImplicitParam不同的是，他是写在参数左侧的。如（ @ApiParam(name="username",value="用户名")Stringusername）
@ApiModel： 描述 POJO对象
@ApiProperty： 描述 POJO对象中的属性值
@ApiImplicitParam： 描述单个入参信息
@ApiImplicitParams： 描述多个入参信息
@ApiResponse： 描述单个出参信息
@ApiResponses： 描述多个出参信息
@ApiError： 接口错误所返回的信息

---

进入 http://localhost:8080/设定的上下文路径/swagger-ui.html 就行了