开发者社区> 问答> 正文

怎么用swagger-ui生成过api文档吗?

游客886 2019-05-23 14:14:05 576

怎么用swagger-ui生成过api文档吗?
本问题来自云栖社区【阿里Java技术进阶1群】。https://yq.aliyun.com/articles/690084 点击链接欢迎加入社区大社群。

Java API
分享到
取消 提交回答
全部回答(2)
  • 阿靖哦
    2019-07-17 23:35:56

    你可以使用我的工具包哦swagger

    1 0
  • soulstart
    2019-07-17 23:35:56

    swagger-ui 和srping项目的整合还是非常简单的,不知道你们的项目是使用的什么架构。推荐可以去官网查看相关使用说明。

    以下是我用springBoot整合Swagger的一个简单案例

    1. 添加依赖:

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

    2. 创建Swagger配置类:
    通过@Configuration注解,让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2通过@Configuration注解,让Spring来加载该类配置。

    Docket是api扫描的接口规则制定对象,代码中是全部扫描,并显示所有rest接口api的Docket方式,实际开发的时候请根据自己需求进行定制。

    ApiInfo是对swagger首页的信息说明对象,也可以根据实际开发需求进行设置。

    @EnableSwagger2
    public class SwaggerConfig {
        @Bean
        public Docket api() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    // 扫描的注解所在的包路径
                    .apis(RequestHandlerSelectors.basePackage("com.jpa.example.demo"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    //设置首页标题
                    .title("api文档")
                    //设置文档整体说明
                    .description("restful 风格接口")
                    //服务条款网址
                    //.termsOfServiceUrl("")
                    .version("1.0")
                    //.contact(new Contact("hello", "url", "email"))
                    .build();
        }
    }

    @EnableSwagger2 指定springBoot初始化时候加载swagger

    @EnableSwagger2 //启动swagger注解d
    public class DemoApplication {
        public static void main(String[] args) {
            SpringApplication.run(DemoApplication.class, args);
        }

    3.使用注解完成接口的说明

    
    import com.jpa.example.demo.bean.User;
    import com.jpa.example.demo.service.IUserService;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiImplicitParam;
    import io.swagger.annotations.ApiOperation;
    import io.swagger.annotations.ApiParam;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.PostMapping;
    import org.springframework.web.bind.annotation.RequestBody;
    import org.springframework.web.bind.annotation.RestController;
    
    import java.util.List;
    
    /**
     * Created By zhangJian on 2019/2/18
     * @Api()
     * 用于类;表示标识这个类是swagger的资源
     * tags–表示说明
     * value–也是说明,可以使用tags替代
     * 但是tags如果有多个值,会生成多个list
     * @description:
     */
    @Api(value = "用户controller",tags = {"用户操作接口"})
    @RestController
    public class UserController {
    
        /**
         * 常用注解:
         * - @Api()用于类;
         * 表示标识这个类是swagger的资源
         * - @ApiOperation()用于方法;
         * 表示一个http请求的操作
         * - @ApiParam()用于方法,参数,字段说明;
         * 表示对参数的添加元数据(说明或是否必填等)
         * - @ApiModel()用于类
         * 表示对类进行说明,用于参数用实体类接收
         * - @ApiModelProperty()用于方法,字段
         * 表示对model属性的说明或者数据操作更改
         * - @ApiIgnore()用于类,方法,方法参数
         * 表示这个方法或者类被忽略
         * - @ApiImplicitParam() 用于方法
         * 表示单独的请求参数
         * - @ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam
         *
         */
    
        @Autowired
        private IUserService userService;
    
        /**
         * value用于方法描述
         * notes用于提示内容
         * tags可以重新分组(视情况而用)
         *
         * @ApiParam() 用于方法,参数,字段说明;表示对参数的添加元数据(说明或是否必填等)
         * name–参数名
         * value–参数说明
         * required–是否必填
         * @param username
         * @return
         */
        @ApiOperation(value = "获取用户信息",tags = {"获取用户信息COPY"},notes = "实现注意事项")
        @GetMapping("/getUserInfo")
        @ApiImplicitParam(name="username",value="用户名",dataType="String", paramType = "query")
        public User getUserInfo(String username){
            User user = userService.getUserInfo(username);
            return user;
        }
    
        @ApiOperation(value="更改用户信息",notes="传入用户对象信息")
        @PostMapping("/updateUser")
        public User updateUser(@RequestBody @ApiParam(name="用户对象",value="传入json格式",required=true)User user){
            return userService.updateUser(user);
        }
    }

    访问http://localhost:8080/swagger-ui.html效果如图:
    image

    点击接口连接可以查看接口的详细说明,入参示例,通过测试数据可以访问接口并返回数据格式,这里当然是针对返回json数据的。
    image

    具体参数说明以及示例可以百度

    1 0
添加回答

集结各类场景实战经验,助你开发运维畅行无忧

推荐文章
相似问题