springboot配置Swagger3.0

springboot配置Swagger3.0

1、pom加入依赖

我们创建一个SpringBoot项目,引入 swagger3 依赖

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-boot-starterartifactId>
    <version>3.0.0version>
dependency>

2、启动类上加入注解

在启动类上加入两个注解,即可开启 swagger3

@SpringBootApplication
@EnableSwagger2
@EnableOpenApi
public class NacosApplication {

    public static void main(String[] args) {
        SpringApplication.run(NacosApplication.class, args);
        System.out.println("我是 nacos 微服务");
    }
}

对于swagger,简单的配置就可以看到页面了,我们我输入 localhost:8080/swagger-ui/index.html

springboot配置Swagger3.0_第1张图片

3、创建Swagger配置类

对于swagger,我们可以对 index.html 页面做一些配置,比如邮箱、姓名、git地址等。

@Configuration
public class SwaggerConfiguration {

    @Bean
    Docket docket() {
        return new Docket(DocumentationType.OAS_30)
                // 配置网站基本信息
                .apiInfo(new ApiInfoBuilder()
                        .title("nacos微服务接口文档")
                        .version("v1.0")
                        .description("在线nacos微服务接口文档")
                        .contact(new Contact("choleen", "https://choleen95.github.io/",
                                ""))
                        .build())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.nacos.controller"))
                .build();

    }

}

目前,对于请求,我们配置了对于controller包下的所有类的接口,都展示在上面。

4、创建接口-三种

目前创建三种接口,一种是form表单传值,一种是路径传参,一种是实体传参

@Api("查询演出接口")
@RequestMapping("/hello/")
@RestController
public class HelloController {

    private static final Logger logger = LoggerFactory.getLogger(HelloController.class);
    @Resource(name = "activityMapper")
    ActivityMapper activityMapper;

    @ApiOperation("根据场地城市及Id查询演出表")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "venueCity", value = "场地城市"),
            @ApiImplicitParam(name = "id", value = "id")
    })
    @GetMapping("activity")
    public ResponseHelper sayHello(String venueCity, @RequestParam(required = true) String id) {
        List<Activity> list = activityMapper.queryEntityList(venueCity, id);
        return ResponseHelper.build(200, list);
    }

    @ApiOperation("根据id查询演出")
    @ApiImplicitParam(name = "id", value = "id")
    @GetMapping("{id}")
    public ResponseHelper queryInfo(@PathVariable(value = "id")Long id) {
        Activity activity = activityMapper.selectById(id);
        return ResponseHelper.build(200, activity);
    }

    @ApiOperation("分页查询演出")
    @ApiImplicitParam(name = "activity", value = "演出实体")
    @GetMapping("queryByPage")
    public ResponseHelper queryByActivity(@RequestBody Activity activity) {
        QueryWrapper<Activity> wrapper = new QueryWrapper<>();
        wrapper.eq("venue_city",activity.getVenueCity()).eq("id",activity.getId());
        PageDTO<Activity> page = new PageDTO<>(1,10);
        PageDTO<Activity> page1 = activityMapper.selectPage(page, wrapper);
        return ResponseHelper.build(200, page1);
    }

}

这里有几个参数需要介绍一下。

  • @Api 在类上,标明此Controller的用处、
  • @ApiOperation 表明此接口的用处
  • @ApiImplicitParam 请求一个入参的说明,有name、value、defaultValue等属性
  • @ApiImplicitParams 若有多个入参,此是一个数组,把多个ApiImplicitParam放进去即可
  • @RequestParam(required=true) 和 @ApiImplicitParam中的必填不同,一个是开发者指定参数必传,一个是swagger调用时必填,但对后台无影响。
  • 若入参是一个实体,比如第三个分页查询 ,可以在实体中也注入 swagger 注解,在前端页面也可让开发者了解参数结构
@Data
@EqualsAndHashCode(callSuper = false)
@ApiModel(value = "activity", description = "演出表")
@TableName("activity")
public class Activity implements Serializable {

    private static final long serialVersionUID = -3563130625676560116L;
    @ApiModelProperty(value = "主键ID")
    private Long id;
    @ApiModelProperty(value = "演出名称")
    private String name;
    @ApiModelProperty(value = "演出起始时间")
    @JSONField(format = "yyyy-MM-dd HH:mm:ss")
    private Date showStartTime;
    @ApiModelProperty(value = "演出结束时间")
    @JSONField(format = "yyyy-MM-dd HH:mm:ss")
    private Date showEndTime;
    @ApiModelProperty(value = "场地城市")
    private String venueCity;
    @ApiModelProperty(value = "场地名称")
    private String venueName;
    @ApiModelProperty(value = "场地地址")
  • @ApiModel 是描述此类的信息
  • @ApiModelProperty 是描述字段的信息

5、swagger调试

接口编写好了,我们可以去 localhost:8080/swagger-ui/index.html 页面上去调试。

springboot配置Swagger3.0_第2张图片

点击 try it 然后再填入参数,点击 Excute ,即可再返回中看到结果。

你可能感兴趣的:(spring,boot,swagger)