zoukankan      html  css  js  c++  java
  • Swagger使用

    原文:https://www.cnblogs.com/liruiloveparents/p/9378327.html

    Swagger学习及生成HTML文档

    Swagger

    1、集成springboot

    第一步:pom

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

    第二步:swagger在springboot中配置

    属性类(省略get/set方法)

    /**
     * swagger配置,生成api
     *
     * @author lirui
     * @date 2018-07-26
     */
    @ConfigurationProperties(prefix = "hyboot.api")
    public class HySwaggerProperties {
    
        /**
         * 是否开启swagger
         */
        private boolean enabled = false;
    
        /**
         * API服务标题
         */
        private String title;
    
        /**
         * API服务描述
         */
        private String description;
    
        /**
         * API服务版本
         */
        private String version;
    
        /**
         * Api负责人相关信息
         */
        private Leader leader = new Leader();
    
        public static class Leader{
    
            /**
             * 负责人姓名
             */
            private String name;
    
            /**
             * 负责人邮箱
             */
            private String email;
        }
    
        /**
         * 用于生成api的html静态文档,需要配置
         */
        private Swagger swagger = new Swagger();
    
        public static class Swagger{
            /**
             * api 接口获取数据地址
             */
            private String apiUrl;
    
            /**
             * 生成文件的位置
             */
            private String filePath;
        }
    }

    配置application.yml

     enabled: false
     title: 测试服务api
     description: 用于测试
     leader:
       name: 汤姆
       email: tom@163.com
     version: 1.0.0

    配置类

    /**
     * swagger配置,生成api
     *
     * @author lirui
     * @date 2018-07-26
     */
    @Configuration
    @EnableConfigurationProperties({HySwaggerProperties.class})
    @EnableSwagger2
    public class HySwaggerAutoConfiguration {
    
        private Logger logger = LoggerFactory.getLogger(HySwaggerAutoConfiguration.class);
        @Autowired
        private ApplicationContext applicationContext;
        
        @Autowired
        private HySwaggerProperties hySwaggerProperties;
        
        @Autowired
        private ServerProperties serverProperties;
    
        /**
         * 定义api生成规则
         *
         * @return
         */
        @Bean
        public Docket hyApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                      //group为系统编号(我们spring的id设置为了系统编号)
                    .groupName(applicationContext.getId())
                    .apiInfo(apiInfo())
                    //支持协议
                    .protocols(Set.of("http", "https"))
                    .select()
                     //限制只有在类上加@Api才添加到swagger,默认是都添加的
                    .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                     //限制只有在方法上加@Api才添加到swagger,默认是都添加的
                    .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    .build();
        }
    
        /**
         * api相关信息
         *
         * @return
         */
        public ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    //服务标题
                    .title(hySwaggerProperties.getTitle() == null ?
                        applicationContext.getId() + "系统服务API" :                                                   hySwaggerProperties.getTitle())
                    //api服务描述
                    .description(hySwaggerProperties.getDescription())
                    //api版本
                    .version(hySwaggerProperties.getVersion())
                    //联系人
                    .contact(
                            new Contact(hySwaggerProperties.getLeader().getName(), "",
                                    hySwaggerProperties.getLeader().getEmail()))
                    .build();
        }
    }

    第三步:访问

    http://host:port/contentPath/swagger-ui.html

    2、生成adoc文件,便于生成HTML/PDF

    主要想法是:Swagger2MarkupConverter(可以根据指定url生成adoc文件,用于生成html),如果想调用当前系统生成adoc文件,就必须保证系统启动完成,这样才能根据url访问

    第一步:定义生成adoc文件的类

    springboot中提供了ApplicationRunner,这个保证了系统启动完执行其中的run方法,所以只要在run方法中调用Swagger2MarkupConverter#from

    /**
     * 系统运行完执行,用于swagger生成adoc文件,继而产生api接口Html静态文件
     * 必须是spring管理的Bean才生效
     * @author lirui
     * @date 2018-07-26
     */
    public class SwaggerCreatAdocRunner implements ApplicationRunner {
    
        /**
         * api 接口获取数据地址
         */
        private String apiUrl;
    
        /**
         * 生成文件的位置
         */
        private String filePath;
    
        @Override
        public void run(ApplicationArguments args) throws Exception {
            try {
                //从指定地址获取数据生成接口文档
                Swagger2MarkupConverter.from(new URL(apiUrl)).build()
                        .toFile(Paths.get(filePath));
    
            } catch (MalformedURLException e) {
                e.printStackTrace();
            }
        }
    
        public String getApiUrl() {
            return apiUrl;
        }
    
        public void setApiUrl(String apiUrl) {
            this.apiUrl = apiUrl;
        }
    
        public String getFilePath() {
            return filePath;
        }
    
        public void setFilePath(String filePath) {
            this.filePath = filePath;
        }
    }

    第二步:swagger配置初始化SwaggerCreatAdocRunner

    就是在上述HySwaggerAutoConfiguration增加了一个SwaggerCreatAdocRunnerspring的bean定义

    (添加了默认不开启Swagger的配置)

    /**
     * swagger配置,生成api
     *
     * @author lirui
     * @date 2018-07-26
     */
    @Configuration
    @EnableConfigurationProperties({HySwaggerProperties.class, ServerProperties.class})
    @EnableSwagger2
    @ConditionalOnExpression("${hyboot.api.enabled:false}")
    public class HySwaggerAutoConfiguration {
    
        private Logger logger = LoggerFactory.getLogger(HySwaggerAutoConfiguration.class);
    
        public static final String LOCALHOST = "127.0.0.1";
    
        @Autowired
        private ApplicationContext applicationContext;
    
        @Autowired
        private HySwaggerProperties hySwaggerProperties;
    
        @Autowired
        private ServerProperties serverProperties;
    
            /**
         * 定义api生成规则
         *
         * @return
         */
        @Bean
        public Docket hyApi() {
            ...
        }
        /**
         * 用于生成swagger API html文档
         * http://localhost:8081/demo/v2/api-docs?group=hyboot-demo
         *
         * @return
         */
        @Bean
        public SwaggerCreatAdocRunner swaggerRunner() {
            //生成api文档的数据来源
            String apiUrl = hySwaggerProperties.getSwagger().getApiUrl();
            String filePath = ClassLoader.getSystemResource("").getPath()+"api";
            //解决window系统路径前带"/"问题
            File file = new File(filePath);
            filePath = file.getPath();
    
            //设置swagger生成adoc文件启动类
            SwaggerCreatAdocRunner swaggerCreatAdocRunner = new SwaggerCreatAdocRunner();
            swaggerCreatAdocRunner.setApiUrl(apiUrl);
            swaggerCreatAdocRunner.setFilePath(filePath);
    
            if (StringUtils.isBlank(apiUrl)) {
                //端口
                int port = serverProperties.getPort();
                //项目
                String contextPath = serverProperties.getServlet().getContextPath();
    
                String group = applicationContext.getId();
                apiUrl = "http://" + LOCALHOST + ":" + port + contextPath + "/v2/api-docs?group=" + group;
    
                swaggerCreatAdocRunner.setApiUrl(apiUrl);
            }
    
            return swaggerCreatAdocRunner;
        }
    
        /**
         * api相关信息
         *
         * @return
         */
        public ApiInfo apiInfo() {
            ...
        }
    }

    第三步:利用上诉生成的adoc文件生成HTML静态文件

    这里要用到maven的插件asciidoctor

     <!--增加swagger生成html-->
     <plugin>
       <groupId>org.asciidoctor</groupId>
       <artifactId>asciidoctor-maven-plugin</artifactId>
       <version>1.5.6</version>
       <configuration>
         <sourceDirectory>${project.basedir}/target/classes/</sourceDirectory>
         <sourceDocumentName>api.adoc</sourceDocumentName>
         <outputFile>${project.basedir}/target/classes/api.html</outputFile>
         <backend>html</backend>
         <sourceHighlighter>coderay</sourceHighlighter>
         <attributes>
           <toc>left</toc>
         </attributes>
       </configuration>
     </plugin>

    执行mvn asciidoctor:process-asciidoc

    在IDEA中直接点击如图即可:

    生成的HTML静态文件

  • 相关阅读:
    前端学习资源
    CSS样式属性单词之Left
    CSS 解决 a标签去掉下划线 text-decoration: none无效 的解决方案
    CSS二级菜单
    position属性absolute与relative 详解
    CSS行高——line-height
    VS code注释快捷键
    CSS padding margin border属性详解
    block(块级元素)和 inline(内联元素) 的区别
    css(float浮动和clear清除)
  • 原文地址:https://www.cnblogs.com/shihaiming/p/9394277.html
Copyright © 2011-2022 走看看