Swagger的使用


Swagger实例

1、在Springboot的Maven项目中,引入以下依赖

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

 

2、创建一个Swagger配置类和启动类同级

package com.ida.wj;

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


/**
 * @author lh
 * @date 2020/7/10
 * @description Swagger配置类
 */
@Configuration
@EnableSwagger2
public class SwaggerApplication {
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)// 指定api类型为swagger2
                .apiInfo(apiInfo())         // // 用于定义api文档汇总信息
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ida.wj.controller"))//指定包名
                .paths(PathSelectors.any())//包下面的所有类
                .build();
    }
    public ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("利用swagger2构建的API文档")
                .description("用restful风格写接口")
                .termsOfServiceUrl("")
                .version("1.0")
                .build();
    }
}

 

3、Controller的配置

    /**
     *  @ApiOperation 用在请求的方法上,说明方法的作用
     *  @ApiResponse  用再请求方法上,表示一组响应
     *  @ApiImplicitParam 用在请求方法上,表示一组参数说明
     */
    @RequestMapping(value ="/api/login",method = RequestMethod.POST)
    @ResponseBody
    @ApiOperation(value = "用户登录",notes = "用户名和密码都是必填项")
    @ApiResponse(code = 400,message = "请求参数没有填好",response = String.class)
    @ApiImplicitParam(name = "user",dataType = "User",required = true)
    public Result login(@RequestBody User user) {
        Result result = new Result();
        String username = user.getUsername();
        String password = user.getPassword();
        //认证
        Subject subject = SecurityUtils.getSubject();
        UsernamePasswordToken token = new UsernamePasswordToken(username,password);
        try{
            subject.login(token);
            result.setCode(200);
            result.setMessage("成功");
        }catch (AuthenticationException e)  {
            result.setCode(1001);
            result.setMessage("用户名或密码错误");

        }
        return result;
    }

 

常用注解说明

1、@Api(value = "xxx", description = "xxx")     :用在类上,用于描述类

2、@ApiOperation(value = "xxx", notes = "xxx")   :用在方法上,value用于描述方法作用,notes备注说明

3、@ApiImplicitParams({@ApiImplicitParam1,@ApiImplicitParam2,...})   :用在方法上,一组参数的说明

4、@ApiImplicitParam  用在 @ApiImplicitParams 注解中,指定一个请求参数的配置信息         

属性:

  • name:字符串 与参数命名对应
  • value:参数的描述
  • required:必填项
  • dataType:参数类型
  • paramType:参数请求方式  
  • query:对应@RequestParam?传递,
  • path: 对应@PathVariable{}path传递

5、@ApiResponses({@ApiResponse1,@ApiResponse2,...})  :用于请求的方法上,表示一组响应

6、@ApiResponse(code = 200, message = "Successful")  :用在@ApiResponses中,一般用于表达一个错误的响应信息

访问结果

地址:http://localhost:8081/swagger-ui.html

 


作者:萧兮易,发布于:2020/07/14
原文:https://www.cnblogs.com/liho/p/13294676.html