Swagger的使用

swagger接口文档

1 前言

Restful API文档在线自动生成工具，API文档与API定义同步更新。

需要Jar包：

• springfox-swagger2
• springfox-swagger-ui

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

问题：输入http://localhost:8080/swagger-ui.html一直无法打开swagger-ui界面

1. 导入的依赖如果是3版本或以上的，只需要在maven中导入如下依赖即可：

   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-boot-starter</artifactId>
       <version>3.0.0</version>
   </dependency>
   

2. 访问路径变为：http://localhost:8080/swagger-ui/index.html

2 配置swagger

• Swagger的bean实例 Docket

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
          //.apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
            //.apis(RequestHandlerSelectors.withClassAnnotation(HelloController.class))
           .apis(RequestHandlerSelectors.basePackage("com.wei.swagger.controller"))
            .build();
        /** RequestHandlerSelectors：配置扫描接口的方式
         *      basePackage：知道要扫描的包
         *      any()：扫描全部
         *      none()：全都不扫描
         *      withClassAnnotation()：扫描类上的注解
         *      withMethodAnnotation()：扫描方法上的注解
         * */ 
    }

    private ApiInfo apiInfo(){
        // 作者信息
        Contact contact = new Contact("linwei", "", "");
        return new ApiInfo(
            "标题",
            "描述",
            "1.0",
            "urn:tos",
            contact,
            "Apache 2.0",
            "http://www.apache.org/licenses/LICENSE-2.0",
            new ArrayList<>());
    }
}

如果需要扫描多个Controller包，则需要将如上的 .apis() 修改为：

.api(
	Predicates.or(
		RequestHandlerSelectors.basePackage("com.wei.fulltext"),
		RequestHandlerSelectors.basePackage("com.wei.commons"),
		.......
		RequestHandlerSelectors.basePackage("com.wei.hive")
	)
)

3 Swagger相关注解

import io.swagger.annotations.*;
import io.swagger.models.Response;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import javax.servlet.http.HttpServletRequest;
import java.util.ArrayList;

@RestController
@Api(tags = "这是一个类", value = "this is class")
@RequestMapping("/")
public class HelloController {

    @GetMapping("/hello")
    @ApiOperation(value = "hello()方法", notes = "return hello")
    @ApiImplicitParams({
          @ApiImplicitParam(name = "userName", value = "用户名称", required = true),
          @ApiImplicitParam(name = "userId", value = "用户编码", required = true)
    })
    public String hello(String userName, String userId){
        return "hello";
    }
}

1. @Api：使用在类上，表示该类是Swagger资源。属性：

   • tags：生成的接口文档都会在tags这个值下面
   • value：若tags没有被使用，启用value的值

2. @ApiOperation：作用在方法上，表示一个http请求的操作。

   • value：用于方法描述；
   • notes：用于提示内容；
   • tage：可重新分组。

3. @ApiImplicitParams：用在请求的参数上，表示一组参数说明。

   • @ApiImplicitParam：表示指定一个请求参数的各个方面。其属性有：
     • name：参数名；
     • value：对该参数的描述；
     • required：表示该参数是否必须，默认为false；
     • dataType：数据类型，默认是String
     • defaultValue：参数的默认值。

4. @ApiModel：用在响应类上，表示一个返回响应数据的信息。

   使用场景：

   • 一般用在@RequestBody；
   • 请求参数无法被@ApiImplicitParam注解进行描述的时候。

5. @ApiResponses：用在请求的方法上，对应一组响应。

   • @ApiResponse：响应信息，一般用于表示错误的响应信息。
     • code：描述接口返回的响应数据的状态码。
     • message：对接口返回的状态码进行描述。
     • response：抛出一场的类。

6. @ApiModelProperty：用在属性上，表示描述相应类的属性。