swagger2简单使用

Posted 2022-05-20 alittlesmile

 

1.引入jar

<!--引入swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>

swaggerConfig.注解使用

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

@Configuration
@EnableSwagger2
public class SwaggerConfig 
    @Bean
    public Docket createRestApi() 

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    

    private ApiInfo apiInfo() 
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("简单优雅的restful风格")
                .termsOfServiceUrl("")
                .version("1.0")
                .build();
    

    private List<ApiKey> securitySchemes() 
        List<ApiKey> apiKeys = new ArrayList<>();
        apiKeys.add(new ApiKey("Authorization", "Authorization", "header"));
        return apiKeys;
    

    private List<SecurityContext> securityContexts() 
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.regex("^(?!auth).*$")).build());
        return securityContexts;
    

    private List<SecurityReference> defaultAuth() 
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
        return securityReferences;
    

3注解使用

import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/swagger2")
public class Swagger2Controller 
    @PostMapping("/hello")
    @ApiOperation(value = "hello",notes = "一个参数")
    @ApiImplicitParam(name = "name",paramType = "query",defaultValue = "lisi")
    public String hello(String name)
        return "hello "+name;
    
    @PostMapping("/info")
    @ApiOperation(value = "info",notes = "两个参数")
    @ApiImplicitParams(
        @ApiImplicitParam(name = "name",paramType = "query",defaultValue = "lisi"),
        @ApiImplicitParam(name = "age",paramType = "query",defaultValue = "15")
    )
    public String info(String name,String age)
        return "hello "+name+", age:"+age;
    

    @PostMapping("/getUser")
    @ApiOperation(value = "getUser",notes = "参数是对象,返回值是对象")
    @ApiImplicitParam(name = "user",paramType = "body",dataType = "User")
    public User getUser(@RequestBody User user)
        return user;
    

 user实体类

import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
public class User 
    @ApiModelProperty(value = "姓名",example = "zhangSan")
    String name;
    @ApiModelProperty(value = "年龄",example = "16")
    String age;

 

 

效果

note: lisi是默认值