Swagger的使用

Swagger可以实时生成接口文档并做接口测试

1.引入依赖

     <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.是Swagger生效

package com.example.activitydemo.swagger;

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

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //生成接口的路径
                .apis(RequestHandlerSelectors.basePackage("com.example.activitydemo.controller"))
                .paths(PathSelectors.any())
                .build();
//        return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();
    }

    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("Spring Boot 使用 Swagger2 构建RESTful API")
                //创建人
                .contact(new Contact("createUser", "URL", "mail"))
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }

}

实体类:

package com.example.activitydemo.swagger;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

//需要自己添加get/set接口，或者使用lumbok，否则swagger界面无法显示相应字段信息
    @Data
    @ApiModel(value = "电影实体",description = "电影实体描述")
public class Film {
    @ApiModelProperty(value = "电影名称",name = "filmName",required = true)
    private String filmName;

    @ApiModelProperty(value = "电影得分",name = "score")
    private String score;


}

3.controller接口

  @ApiOperation(value = "test1功能接口")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "param1",value ="参数一",dataType = "string",required = true,paramType = "path"),
            @ApiImplicitParam(name = "param2",value ="参数二",dataType = "string",required = true,paramType = "path")
    })
    @PostMapping(value = "/test1")
    public String test1(String param1, String param2){
        return "ok";
    }

    @ApiOperation(value = "test2功能接口")
    @PostMapping(value = "/test2")
    public Film test2(@ApiParam(value = "电影实体对象")  @RequestBody Film film){
        return film;
    }

    @RequestMapping("/{id}")
    TestPerson showUserForm(@PathVariable("id") TestPerson user) {
        //参数实体TestPerson必须使用@Entity标识的实体类
        //会自动根据传参的ID自动调用findById方法查询

        return user;
    }

4.Swagger界面访问:http://localhost:8089/swagger-ui.html

5.相关注解说明

@Api(value = "test相关接口",tags = {"tag1","tag1"})，一般用在Controller类上
@ApiOperation(value = "test1功能接口"),表明某个特定接口的作用