当前位置：首页 > news >正文

Swagger 使用教程

news 2025/7/5 0:00:47

Swagger

官网： API Documentation & Design Tools for Teams | Swagger

整合swagger

依赖：

springfox-swagger2
springfox-swagger-ui

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger2</artifactId>

    <version>2.9.2</version>

</dependency>

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger-ui</artifactId>

    <version>2.9.2</version>

</dependency>

配置swagger容器

package com.oo.swagger_demo.config;

/**

* Description:

*

* @author:wuxinke

* @date: 2021-06-07 23:02

* @param:

* @return:

*/

import org.springframework.context.annotation.*;

import org.springframework.core.env.*;

import springfox.documentation.builders.*;

import springfox.documentation.service.*;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration

@EnableSwagger2 //开启swagger2

public class SwaggerConfig {

    @Bean

    //Environment:获取当前的生产环境

    public Docket createRestApi(Environment environment){

        //设置要显示的swagger环境

        Profiles profiles = Profiles.of("dev");

        //通过environment.acceptsProfiles(),判断是否处在自己设定的环境中

        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)

                .apiInfo(apiInfo())

                //.enable(flag)//是否启动swagger，如果为false，则swagger不能再游览器中访问

                .select()

                //RequestHandlerSelectors.any()：扫描全部

                //RequestHandlerSelectors.none()：不扫描

                //RequestHandlerSelectors.basePackage()：扫描指定包

                //RequestHandlerSelectors.withClassAnnotation()：扫描类上的注解，参数是一个注解的发射对象

                //RequestHandlerSelectors.withMethodAnnotation()：扫描方法上的注解，参数是一个注解的发射对象

                .apis(RequestHandlerSelectors.basePackage("com.oo.swagger_demo.controller"))//扫描接口

                //.paths(PathSelectors.ant("/admin/**"))//过滤什么路径

                .build();

    }

    private ApiInfo apiInfo(){

        Contact contact = new Contact("", "", "");

        return new ApiInfo("吴新科接口", "属于吴新科第一次开发swagger接口测试", "1.0", "urn:tos", contact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());

    }

}

配置API的分组

.groupName("吴新科")

@Bean

public Docket getDocket1(){

    return new Docket(DocumentationType.SWAGGER_2)

            .groupName("张三");

}

@Bean

public Docket getDocket2(){

    return new Docket(DocumentationType.SWAGGER_2)

            .groupName("李四");

}

@Bean

public Docket getDocket3(){

    return new Docket(DocumentationType.SWAGGER_2)

            .groupName("王五");

}

swagger注解

实体类：

ApiModel：对象注明

ApiModelProperty：属性注明

控制层：

Api:类注明

ApiOperation：方法注明

ApiParam：参数注明

列举：

@ApiModel(value="AppIndent对象", description="订单表")

public class AppIndent extends Model<AppIndent> {

    private static final long serialVersionUID = 1L;

    @ApiModelProperty(value = "主键")

    @TableId(value = "id", type = IdType.AUTO)

    private Long id;

    @ApiModelProperty(value = "姓名")

    @TableField("name")

    private String name;

}

@RestController

@RequestMapping("/app/appIndent")

@Api(value = "地址相关",tags = "地址相关")

public class AppIndentController extends BaseController{

    /**

    * Description: 点击选择上门地址，展示该用户的所有地址

    * @Author:吴新科

    * @Date:2021/5/6 9:35

    * @Param: pageNum:起始索引，pageSize：每页几条

    */

    @GetMapping("/list")

    @ApiOperation(value = "订单列表展示", notes = "订单列表展示")

    public ResultPage<AppIndent> list(@ApiParam(value = "起始索引")

   @RequestParam Integer pageNum,@ApiParam(value = "每页几条") @RequestParam Integer pageSize){

        return appIndentService.userIdList(getUserId(),pageNum,pageSize);

    }