微服务swagger解析部署使用全流程

news2024/11/28 12:34:41

1、介绍

swagger是一个在线接口说明文档，在代码中通过注解的方式将说明问题集成到项目，代码发生修改，说明文档同步修改，前后台联调可以快速同步数据。

2、应用

1、引入依赖

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

2、编写配置类

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;

/**
 * @author szsw
 * @date 2023/3/1 18:12:17
 */
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket docket() {
        /*采用swagger2版本*/
        return new Docket(DocumentationType.SWAGGER_2)
                /*生成api相关信息*/
                .apiInfo(createApiInfo())
                /*返回一个apiSelectorBuilder对象，用来控制接口生成在线文档*/
                .select()
                /*扫描某个包下的接口*/
                .apis(RequestHandlerSelectors.basePackage("org.jsoft.demo.controller"))
                /*生成所有的api*/
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建api相关信息
     *
     * @return ApiInfo
     */
    private ApiInfo createApiInfo() {
        return new ApiInfoBuilder()
                /*自定义title*/
                .title("swagger demo")
                /*描述*/
                .description("swagger示例")
                /*定义服务域名*/
                .termsOfServiceUrl("")
                /*自定义版本号*/
                .version("0.0.1")
                .build();
    }

}

3、开启Swagger

@EnableSwagger2                 启动器

4、编写示例

1、实体类

package org.jsoft.demo.dto;

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

import java.util.Date;


@Data
@ApiModel
public class UserUpdateDto {

    @ApiModelProperty(value = "主键", required = true, example = "asdfa54s56d")
    private String id;
    @ApiModelProperty(value = "名字", required = true, example = "张三")
    private String name;
    @ApiModelProperty(value = "密码", required = true, example = "123456")
    private String password;
    @ApiModelProperty(value = "年龄", required = true, example = "20")
    private Integer age;
    @ApiModelProperty(value = "生日", required = true, example = "1998-07-07")
    private Date birthday;
    @ApiModelProperty(value = "分数", example = "100.5")
    private Double score;

}
/*
value 描述
required 必填项
example 举例
*/

package org.jsoft.demo.dto;

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

import java.util.Date;


@Data
@ApiModel
public class UserAddDto {

    @ApiModelProperty(value = "名字", required = true, example = "张三")
    private String name;
    @ApiModelProperty(value = "密码", required = true, example = "123456")
    private String password;
    @ApiModelProperty(value = "年龄", required = true, example = "20")
    private Integer age;
    @ApiModelProperty(value = "生日", required = true, example = "1998-07-07")
    private Date birthday;
    @ApiModelProperty(value = "分数", example = "100.5")
    private Double score;

}

2、Controller

package org.jsoft.demo.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.jsoft.demo.dto.UserAddDto;
import org.jsoft.demo.dto.UserUpdateDto;
import org.jsoft.demo.utils.Result;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

import java.util.Map;


@Api(tags = "用户")
@RestController
@RequestMapping("/user")
public class UserController {

    @PostMapping
    @ApiOperation("用户新增")
    public Result add(@RequestBody UserAddDto dto) {
        return Result.ok();
    }

    @DeleteMapping("/{id}")
    @ApiOperation("用户删除")
    @ApiImplicitParams({
            @ApiImplicitParam(value = "删除的用户主键", name = "id", paramType = "path")
    })
    public Result delete(@PathVariable String id) {
        return Result.ok();
    }

    @PutMapping
    @ApiOperation("用户修改")
    public Result update(@RequestBody UserUpdateDto dto) {
        return Result.ok();
    }

    @GetMapping("/{id}")
    @ApiOperation("用户详情")
    @ApiImplicitParams({
            @ApiImplicitParam(value = "用户主键", paramType = "path")  //path是指地址传参。
    })
    public Result info(@PathVariable String id) {
        return Result.ok();
    }

    @GetMapping
    @ApiOperation("用户查询")
    @ApiImplicitParams({
            @ApiImplicitParam(value = "姓名", name = "name", paramType = "query"),
            @ApiImplicitParam(value = "年龄", name = "age", paramType = "query"),
            @ApiImplicitParam(value = "分数", name = "score", paramType = "query")  // get地址栏传参
    })
    public Result query(@ApiIgnore @RequestParam Map<String, String> params) {
        return Result.ok();
    }

}