springboot如何使用swagger-优快云博客

本文链接：https://blog.youkuaiyun.com/bxy0806/article/details/132338619

springboot中使用swagger可以自动生成接口说明文档，是我们开发api接口的利器，下面说一下springboot快速集成swagger的步骤。
一、快速集成
1、maven的pom.xml加入依赖

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

增加swagger2配置文件

@Configuration
@EnableSwagger2
public class Swagger2Config{
    @Bean
    public Docket getUserDocket(){
        ApiInfo apiInfo=new ApiInfoBuilder()
                .title("用户管理")//api标题
                .description("用户管理相关接口描述")//api描述
                .version("1.0.0")//版本号
                .contact("sabre")//本API负责人的联系信息
                .build();
        return new Docket(DocumentationType.SWAGGER_2)//文档类型（swagger2）
                .apiInfo(apiInfo)//设置包含在json ResourceListing响应中的api元信息
                .select()//启动用于api选择的构建器
                .apis(RequestHandlerSelectors.basePackage("com.candy.control"))//扫描接口的包
                .paths(PathSelectors.any())//路径过滤器（扫描所有路径）
                .build();
    }
}

或

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxxxxxx.tsp.rps.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("TSP订单资源接口Api")
                .description("TSP订单资源接口Api")
                .termsOfServiceUrl("")
                .contact("devteam")
                .version("1.0")
                .build();
    }

常用注解如下：

注解	使用的地方	用途
@Api	类/接口	描述类/接口主要用途
@ApiOperation	方法	描述方法的用途
@ApiImplicitParam	方法	用于描述接口的非对象参数
@ApiImplicitParams	方法	用于描述接口的非对象参数集
@ApiIgnore	类/方法/参数	Swagger 文档不会显示拥有该注解的接口
@ApiModel	参数实体类	可设置接口相关实体的描述
ApiModelProperty	参数实体类属性	可设置实体属性的相关描述

在参数实体类上加上注解@ApiModel

@ApiModel("用户")public class UserInfo {
    
    @ApiModelProperty("用户ID")
    private Integer id;
    
    @ApiModelProperty("用户代码")
    private String userCode;
    
    @ApiModelProperty("用户姓名")
    private String userName;
    
    @ApiModelProperty("年龄")
    private Integer age;
}

在接口类上加上注解@Api

接口代码：

@Api("用户登录接口api")
@RestController
@RequestMapping("/login")
public class LoginedController {
    @Autowired
    LoginService loginService;
    @RequestMapping("/logined")
    public String logined(UserInfo userInfo){
       boolean ok= loginService.login(userInfo);
       if(ok){
           return "ok";
       }else {
           return "eg";
       }
    }
}

大部分情况下，访问项目地址，后面加"/swagger-ui.html"就会出现如下界面：

二、可能出现的问题
1、出现 no mapping的情况，需要增加一个 WebMvcConfigurerConfig，代码如下：

@Configuration
public class WebMvcConfigurerConfig extends WebMvcConfigurerAdapter  {


    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("support/swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("support/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");

    }
}

2、需要访问权限的情况，如果你的项目均需要token验证，则需要在springboot的配置文件增加以下内容：

security.ignored=/swagger-ui.html,/swagger-ui.html/*,/webjars/**,/error,/swagger-resources/**

三、注解规范
1、【必填】@Api(value = “”, tags = “”)
此注解应用在类上面，表示对类的说明。其中，
（1）tags=“说明该类的作用，可以在UI界面上看到的注解” （非空时将覆盖value的值）
（2）value=“说明类的作用”

例：

@Api(value="影城配置",tags={"影城后台配置"})

2、【必填】@ApiOperation(notes = “”, value = “”)
此注解作用在方法上面，说明该方法的用途等
（1）value=“说明该方法的作用和用途”
（2）notes=“对该方法的备注信息说明”

例：

@ApiOperation(value="修改影城退改签配置",notes="输入参数为影城退改签配置的json")

3、【非必填】@ApiImplicitParams
此注解作用在类上，表明对一组参数的说明
@ApiImplicitParam 用在@ApiImplicitParams注解的内部，表明对一组参数的各个方面进行具体的说明
（1）name参数名
（2）value对参数的说明
（3）required参数是否必传（值为true或者false）
（4）dataType参数类型，默认是String，其他例如：Integer
（5）paramType 参数放在什么地方
· header --> 请求参数的获取：@RequestHeader ·
query --> 请求参数的获取：@RequestParam ·
path（用于restful接口）–> 请求参数的获取：@PathVariable ·
body（不常用） ·
form（不常用）

例：

@ApiImplicitParams({
        @ApiImplicitParam(name = "configs", value = "影院退改签规则", required = true, paramType = "body", dataType = "List")
})

4、【非必填】@ApiResponses：用在请求的方法上，表示一组响应
@ApiResponse用在@ApiResponses中，常用于表示一组错误的信息的响应
（1）code错误代码
（2）massege错误信息提示
（3）response 抛出异常的类
示例：

@ApiResponses({ 
            @ApiResponse(code=400,message="请求参数没填好"),
            @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
        })

5、【非必填】@ApiParam用在请求方法中，描述参数的信息
name参数名称，参数名称可以覆盖方法参数名称，路径参数必须与方法参数一致
value参数的简要说明。
defaultValue参数默认值
required 属性是否必填，默认为false [路径参数必须填]
示例：

@PostMapping(value="/login")
@ApiOperation(value = "登录检测", notes="根据用户名、密码判断该用户是否存在")
public UserModel login(@ApiParam(name = "name", value = "用户名", required = false) @RequestParam(value = "name", required = false) String account,
                @ApiParam(name = "pass", value = "密码", required = false) @RequestParam(value = "pass", required = false) String password){}

6、【非必填】@ApiIgnore用在类或者方法上，表明在swagger2中忽略这个类或者方法或者参数

public void updateRefundFee(@RequestBody List<CinemaRefundAlterFeeRule> configs, @ApiIgnore UserProfile userProfile) {
        cinemaService.updateRefundFee(configs,userProfile.getName());
    }

四、生成环境禁用swagger
在配置文件中，增加profile的限制。