当前位置：网站首页>Swagger simple quick start tutorial

Swagger simple quick start tutorial

2022-07-25 04:18:00 【51CTO】

One 、 Use springfox Generate interface UI

1、 Import springfox-boot-starter rely on

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
</dependency>

     1.
2.
3.
4.
5.

2、 To configure config

@Configuration
@EnableOpenApi
@Slf4j
public  class SwaggerConfig extends WebMvcConfigurationSupport {

    /** *  Set static resource mapping  */
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        log.info(" Start static resource mapping ....");
        registry.addResourceHandler("/backend/**").addResourceLocations("classpath:/backend/");
        registry.addResourceHandler("/front/**").addResourceLocations("classpath:/front/");
        registry.addResourceHandler("/swagger-ui/**").addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/");
    }


    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.OAS_30) //  Select the document type  OpenApi 3.0
                .apiInfo(apiInfo()) // To configure swagger Information 
                .enable(true)  //  Open or not   Default on ;
                .groupName("reggie") // reggie
                .select() //  choice 
                .apis(RequestHandlerSelectors.basePackage("com.xy.reggie.controller")) //  Classes under the scanned package path 
                .build(); //  establish 
    }

    private ApiInfo apiInfo() {
        return new ApiInfo(
                "reggie  file ",
                "reggie  file ",
                "v1.0",
                "https://www.xxx.edu.cn/",
                new Contact(" Xie Yang ", "https://blog.51cto.com/learningfish", "[email protected]"),
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

     1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.

3、swagger Of Api Introduce

full name	describe
@Api	Mark the class as Swagger resources （ Generally used to describe Controller）
@ApiImplicitParam	Express API Single parameter in operation （ Generally used to describe specific method parameters ）
@ApiImplicitParams	Allow multiple ApiImplicitParam Wrapper for object list （ It's usually used for packages @ApiImplicitParam）
@ApiModel	Provide relevant Swagger Other information about the model （ Generally used to describe Controller Of method parameters pojo class ）
@ApiModelProperty	Add and manipulate data for model properties （ Generally used to describe pojo Properties of ）
@ApiOperation	Describe the operation for a specific path or usually HTTP Method .（ Generally used to describe Controller Method ）
@ApiParam	Add additional metadata for operation parameters .
@ApiResponse	Describe the possible response of the operation .
@ApiResponses	Allow multiple ApiResponse Wrapper for object list .
@Authorization	Declare the authorization scheme to be used on the resource or operation .
@AuthorizationScope	describe OAuth2 Scope of Authorization .

@Api Usage is as follows :

@Slf4j
@RestController
@RequestMapping("/category")
@Api(tags = " Classification related interfaces ")
public class CategoryController {
}

     1.
2.
3.
4.
5.
6.

@ApiOperation Usage is as follows :

@ApiOperation(" Add dishes ")
@CacheEvict(value = "categoryCache",allEntries = true)
@PostMapping
public R<String> addCategory(@RequestBody Category category) {
    log.info(" Add categories category{}", category);
    categoryService.save(category);
    return R.success(" Adding dish classification succeeded ");
}

     1.
2.
3.
4.
5.
6.
7.
8.

@ApiImplicitParams、@ApiImplicitParam Usage is as follows :

@ApiOperation(" Request paging ")
@Cacheable(value = "categoryCache",key = "#pageNum + '_' + #pageSize" )
@GetMapping("/page")
@ApiImplicitParams({
        @ApiImplicitParam(name = "page",value = " Page number ",required = true),
        @ApiImplicitParam(name = "pageSize",value = " Records per page ",required = true),
})
public R<Page> page(@RequestParam("page") Integer pageNum,
                    @RequestParam("pageSize") Integer pageSize) {
    log.info("category Sort and page ");
    Page<Category> categoryPageInfo = new Page<>(pageNum, pageSize);
    LambdaQueryWrapper<Category> queryWrapper = new LambdaQueryWrapper<>();
    queryWrapper.orderByAsc(Category::getSort);
    categoryService.page(categoryPageInfo, queryWrapper);
    return R.success(categoryPageInfo);
}

     1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.

@ApiModel、@ApiModelProperty Usage is as follows :

@Data
@ApiModel(" classification ")
public class Category implements Serializable {

    private static final long serialVersionUID = 1L;

    @ApiModelProperty(" Primary key ")
    private Long id;


    // type  1  Classification of dishes  2  Package classification 
    @ApiModelProperty(" type  1  Classification of dishes  2  Package classification ")
    private Integer type;


    // Category name 
    @ApiModelProperty(" Category name ")
    private String name;


    // The order 
    @ApiModelProperty(" The order ")
    private Integer sort;
}

     1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.

visit swagger-ui/index.html Interface ：

Swagger Simple quick start tutorial _spring

Two 、 Use knife4j Generate interface UI

1、 Import knife4j-spring-boot-starter rely on

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

     1.
2.
3.
4.
5.

2、 To configure config

@Configuration
@EnableOpenApi
@Slf4j
public  class SwaggerConfig extends WebMvcConfigurationSupport {

    /** *  Set static resource mapping  */
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        log.info(" Start static resource mapping ....");
        registry.addResourceHandler("/backend/**").addResourceLocations("classpath:/backend/");
        registry.addResourceHandler("/front/**").addResourceLocations("classpath:/front/");
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }


    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.OAS_30) //  Select the document type  OpenApi 3.0
                .apiInfo(apiInfo()) // To configure swagger Information 
                .enable(true)  //  Open or not   Default on ;
                .groupName("reggie") // reggie
                .select() //  choice 
                .apis(RequestHandlerSelectors.basePackage("com.xy.reggie.controller")) //  Classes under the scanned package path 
                .build(); //  establish 
    }

    private ApiInfo apiInfo() {
        return new ApiInfo(
                "reggie  file ",
                "reggie  file ",
                "v1.0",
                "https://www.xxx.edu.cn/",
                new Contact(" Xie Yang ", "https://blog.51cto.com/learningfish", "[email protected]"),
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

     1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.