spring boot项目使用（1）-- swagger ui

使用swagger ui的出发点就是在日常的开发中的接口开发常常受累于接口文档的编写，

想用一套更简单的方式将接口的定义给到前端（app或者vue等）。

下面开始我们的项目：

1.maven依赖
<!-- springboot web 的依赖-->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-web</artifactId>
  <version>1.5.6.RELEASE</version>
</dependency>
<dependency> 
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.8.0</version>
</dependency>
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.8.0</version>
</dependency>

2.创建springboot启动类 1525871753(1).png

@SpringBootApplication
public class Application {
  public static void main(String[] args) {
    SpringApplication.run(Application.class, args);
  }
}

3.配置项目路径及项目名称

在项目的resource目录下，创建application.yml 1525872079(1).png
内容如下： 1525872187(1).png

不配置项目名称，直接访问swagger ui 的界面弹出个错的的提示，有兴趣的可以试试。

4.添加swagger的配置类SwaggerConf 1525872531(1).png

package com.wyl.autoConf;

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConf {

    @Bean
    public Docket createRestApi() {
    /** 内置参数
    this.apiInfo = ApiInfo.DEFAULT;
    this.groupName = "default";
    this.enabled = true;
    this.genericsNamingStrategy = new DefaultGenericTypeNamingStrategy();
    this.applyDefaultResponseMessages = true;
    this.host = "";
    this.pathMapping = Optional.absent();
    this.apiSelector = ApiSelector.DEFAULT;
    this.enableUrlTemplating = false;
    this.vendorExtensions = Lists.newArrayList();
    this.documentationType = documentationType;
    */
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            //这是一个很重要的参数，当你不想让人看到swagger ui 需要将值设置为false
            .enable(true)
            .select()
            //设置扫描的包路径
            .apis(RequestHandlerSelectors.basePackage("com.wyl"))
            //设置扫描哪些controller，可以匹配正则，这里是全扫描
            .paths(PathSelectors.any())
            .build();
    }

    private ApiInfo apiInfo() {
    /** 内置的参数，可以自己选择
    private String title;名字
    private String description;描述
    private String termsOfServiceUrl;
    private Contact contact;
    private String license;
    private String licenseUrl;
    private String version;
    */
        return new ApiInfoBuilder()
            .title("swagger测试")
            .contact(new Contact("wyl", "https://www.jianshu.com/u/838d4c782a71", "1037424761@qq.com"))
            .version("1.0")
            .build();
    }
}

5.节下来我们就可以在接口中使用swagger ui 了

写一个简单的接口

1525874704(1).png

常用的注释说明：

5.1. @Api
用在类上，说明该类的作用
@Api(value = "UserController", description = "用户相关api")

5.2 @ApiOperation
用在方法上，说明方法的作用
@ApiOperation(value = "查找用户", notes = "查找用户", httpMethod = "GET", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)

5.3 @ApiImplicitParams
用在方法上包含一组参数说明

5.4. @ApiImplicitParam
用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
paramType：参数放在哪个地方
header–>请求参数的获取：@RequestHeader
query–>请求参数的获取：@RequestParam
path（用于restful接口）–>请求参数的获取：@PathVariable
body（不常用）
form（不常用）
name：参数名
dataType：参数类型
required：参数是否必须传
value：参数的意思
defaultValue：参数的默认值

@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "唯一id", required = true, dataType = "Long", paramType = "path"),
})
5.5. @ApiResponses
用于表示一组响应

5.6. @ApiResponse
用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如”请求参数没填好”
response：抛出异常的类

@ApiResponses(value = {
@ApiResponse(code = 400, message = "No Name Provided")
})
5.7. @ApiModel
描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModel(value = "用户实体类")

5.8. @ApiModelProperty
描述一个model的属性
@ApiModelProperty(value = "登录用户")

当我们启动项目下，访问http://127.0.0.1:8088/wyl/swagger-ui.html#
看到如下的界面：

1525875079(1).png
表示swagger ui的使用成功

关于swagger ui 使用的疑惑：

1.swagger ui 人人都可以访问，会不会提高接口被攻击的风险？
很多小伙伴在使用的时候还会配置一个token ，用来识别请求的合法性。其实我觉得没什么必要，任何前端的访问，都会走一个统一的拦截网关（不同的公司实现的方式不同），到请求接口的时候，其实是一个相对安全的内王网环境。
2.swagger ui 可以替换接口文档吗？
其实在使用中，我们发现，其实接口文档还是需要的，只是在开发中减少了反复修改接口文档的困扰。