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

 

引入swagger-bootstrap-ui

1、在pom文件中加入swagger-bootstrap-ui依赖的文档（加强版，功能更加强大）

<!-- 引入swagger-bootstrap-ui依赖包-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.8.7</version>
</dependency>
2、访问地址：http://localhost:8081/doc.html